TOML in 2 Minutes: A Short and Informative Guide

The productive configuration file format for developers

Published in

ITNEXT

2 min readApr 19, 2024

TOML stands for “Tom’s Obvious, Minimal Language”. It’s a configuration file format that’s easy to read and has noticeable advantages over alternatives like json for configuration files. Here is the basic syntax.

# Primitive Values
enable = true
initial_value = "string"
value = 0

# Tables (Hash tables or dictionaries)
[check_ticket]
infer_ticket = true
title_position = "start"

# Arrays of Tables
[commit_scope]
  
  [[commit_scope.options]]
  value = "app"
  label =  "Application"

  [[commit_scope.options]]
  value = "share"
  label =  "Shared"

  [[commit_scope.options]]
  value = "tool"
  label =  "Tools"

For an in-depth breakdown of the syntax, see the documentation.

Use Cases

Configuring libraries: Many projects use toml for configuration (namely projects written in Rust). Knowing toml helps you configure libraries like Starship, a highly-flexible terminal prompt.
Improve your projects: toml is a great choice for creating configuration files in your own side projects
Party trick: Your popularity at parties will sky-rocket as you explain how json is the inferior choice for configuration files

A Concrete Example — JSON vs TOML

I have a side-project that uses json for it’s configuration file. — Here’s a comparison of the exact same configuration in json and toml.

Pros

toml has less bloat: A json file is filled with quotes, curly braces, and commas. So much so, that toml files are actually smaller when measured in bytes for the exact same configuration (in this example 700 bytes smaller).
control indentation: Looking at the line with "value": "app", the line is indented 4 tabs in json. The equivalent, only uses 1 tab in toml. Additonally, toml lets you configure indentation to your liking
toml supports comments: You can write (and syntax highlight) comments in a toml file

Resources

Further reading and examples below. — If you enjoyed this article, consider checking out Flotes. It’s the Markdown note taking and study application we use to learn and research topics like the one in this article.

Learn More

Ecosystem (Real World Examples)

Originally published at https://blog.flotes.app.