Convert ADOC to TOML

Why Convert ADOC to TOML?

Converting AsciiDoc documents to TOML format bridges the gap between documentation and configuration. This is particularly useful when your documentation contains structured settings, project metadata, or configuration specifications that need to be transformed into actual TOML configuration files used by modern development tools.

TOML (Tom's Obvious Minimal Language) was created in 2013 by Tom Preston-Werner, co-founder of GitHub, specifically to be a minimal configuration format that maps unambiguously to a hash table. Unlike INI files, TOML has a formal specification, supports complex data types, and handles nested structures elegantly. It's become the standard for Rust projects (Cargo.toml) and Python packaging (pyproject.toml).

AsciiDoc's structured nature with sections, attributes, and definition lists maps well to TOML's tables and key-value pairs. Document sections become TOML tables, definition lists become typed key-value pairs, and document attributes translate to top-level configuration values. This makes extracting configuration data from documentation straightforward.

This conversion is invaluable for DevOps and development workflows where configuration specifications documented in AsciiDoc need to be transformed into working TOML files. It's also useful for generating project scaffolding, creating configuration templates, or migrating documented settings into modern configuration formats.

Key Benefits of Converting ADOC to TOML:

• Modern Configuration: Generate files for Rust, Python, and modern tooling
• Typed Values: TOML preserves data types (strings, numbers, booleans)
• Clear Specification: TOML has formal, unambiguous semantics
• Nested Structures: Support for complex hierarchical configuration
• Array Support: Native arrays and tables of arrays
• Documentation to Code: Transform specs into working config
• DevOps Integration: Perfect for CI/CD and deployment configs

Practical Examples

Example 1: Rust Project Configuration

Input AsciiDoc file (project-spec.adoc):

= My Rust Project
:name: my-project
:version: 0.1.0
:edition: 2021

== Package

name:: my-project
version:: 0.1.0
edition:: 2021
authors:: ["Developer "]

== Dependencies

serde:: 1.0
tokio:: { version = "1.0", features = ["full"] }

Output TOML file (Cargo.toml):

[package]
name = "my-project"
version = "0.1.0"
edition = "2021"
authors = ["Developer "]

[dependencies]
serde = "1.0"
tokio = { version = "1.0", features = ["full"] }

Example 2: Python Project Configuration

Input AsciiDoc file (python-project.adoc):

= Python Package Configuration

== Build System

requires:: ["setuptools>=61.0"]
build-backend:: "setuptools.build_meta"

== Project

name:: my-python-package
version:: 1.0.0
description:: A sample Python package
requires-python:: >=3.8
license:: MIT

Output TOML file (pyproject.toml):

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-python-package"
version = "1.0.0"
description = "A sample Python package"
requires-python = ">=3.8"
license = "MIT"

Example 3: Application Settings

Input AsciiDoc file (app-settings.adoc):

= Application Configuration
:title: My Application

== Server

host:: "0.0.0.0"
port:: 8080
debug:: false
workers:: 4

== Database

url:: "postgres://localhost/mydb"
pool_size:: 10
timeout:: 30

Output TOML file (config.toml):

title = "My Application"

[server]
host = "0.0.0.0"
port = 8080
debug = false
workers = 4

[database]
url = "postgres://localhost/mydb"
pool_size = 10
timeout = 30

Frequently Asked Questions (FAQ)

Q: What is TOML and why is it popular?

A: TOML (Tom's Obvious Minimal Language) is a configuration file format created in 2013 by Tom Preston-Werner, GitHub's co-founder. It's designed to be minimal, obvious, and easy to read. TOML is popular because it has a clear specification, supports typed values (strings, integers, floats, booleans, dates), and handles nested structures well. It's the default format for Rust's Cargo, Python's pyproject.toml, and many modern tools.

Q: How does TOML compare to YAML and JSON?

A: TOML is more readable than JSON (no excessive braces/brackets) and safer than YAML (no indentation sensitivity, explicit typing). Unlike YAML, TOML has a formal specification and fewer edge cases. It's less powerful than YAML for complex data but more suitable for configuration files. JSON is better for data exchange, while TOML excels at human-edited configuration.

Q: Will my AsciiDoc formatting be preserved?

A: TOML is a data format, not a document format, so rich formatting (bold, italic, lists as prose) will be converted to plain text values. However, structured data like sections, attributes, and definition lists map well to TOML tables and key-value pairs. The conversion focuses on extracting configurable data from your documentation.

Q: Can I use the output as a Cargo.toml file?

A: The generated TOML is syntactically valid and can serve as a starting point for Cargo.toml or other configuration files. However, you may need to adjust the structure and keys to match Cargo's expected schema. The conversion extracts structured data but doesn't automatically know which fields Cargo requires.

Q: How are nested sections handled?

A: AsciiDoc nested sections (=== subsection under == section) are converted to TOML's dotted key syntax ([section.subsection]). This preserves the hierarchical structure of your document in a way that TOML parsers can properly interpret as nested tables.

Q: Does TOML support arrays from AsciiDoc lists?

A: Yes! AsciiDoc unordered and ordered lists can be converted to TOML arrays. For example, a list under a definition term becomes an array value: items = ["item1", "item2", "item3"]. TOML also supports arrays of tables using [[array.syntax]] for more complex structures.

Q: What tools can read TOML files?

A: TOML is widely supported: Python 3.11+ includes tomllib in the standard library; Rust has native support via the toml crate; Node.js has @iarna/toml and other packages. Go, Java, .NET, PHP, and most other languages have TOML libraries. Many development tools (Cargo, Poetry, Hugo, Netlify) use TOML natively.

Q: Is TOML suitable for all configuration needs?

A: TOML is excellent for most application configuration but has limitations. Very deeply nested structures can become verbose, and it doesn't support binary data or complex object references. For simple to moderately complex configuration, TOML is ideal. For data serialization or deeply nested data, JSON or a custom format might be better.