Convert AsciiDoc to TOML

Why Convert AsciiDoc to TOML?

Converting AsciiDoc to TOML is useful when you need to extract structured data from documentation and transform it into configuration files. AsciiDoc documents often contain project metadata, dependency lists, configuration tables, and settings descriptions that can be directly mapped to TOML key-value structures. This conversion bridges the gap between human-readable documentation and machine-parseable configuration.

TOML, created by Tom Preston-Werner (co-founder of GitHub) in 2013, was specifically designed to be an obvious, minimal configuration format. Its key strength lies in readability: every TOML construct maps unambiguously to a hash table, making it straightforward for both humans and machines to parse. The format has gained significant adoption in modern development ecosystems, including Rust (Cargo.toml), Python (pyproject.toml), and Hugo (config.toml).

The conversion process analyzes the AsciiDoc document structure and extracts key-value information from attributes, tables, definition lists, and structured sections. Document attributes like :version: 1.0 naturally map to TOML key-value pairs. Tables are converted to TOML arrays of tables, and hierarchical sections become nested TOML tables. The resulting TOML file maintains the logical structure of the original document while conforming to TOML's strict typing rules.

This conversion is particularly valuable for DevOps teams who document their infrastructure configurations in AsciiDoc but need TOML files for deployment tools. It also benefits open-source projects that want to generate pyproject.toml or Cargo.toml files from documented specifications, ensuring consistency between documentation and actual configuration.

Key Benefits of Converting AsciiDoc to TOML:

• Configuration Generation: Create config files from documented specifications
• Rust Ecosystem: Generate Cargo.toml from project documentation
• Python Projects: Produce pyproject.toml from documented metadata
• Type Safety: TOML enforces strong typing for strings, numbers, booleans, and dates
• Readable Output: TOML is designed to be human-friendly and obvious
• Data Extraction: Pull structured settings from narrative documentation
• Automation: Bridge documentation and deployment configuration pipelines

Practical Examples

Example 1: Project Metadata Extraction

Input AsciiDoc file (project-info.adoc):

= MyApp Configuration
:project-name: myapp
:version: 3.2.1
:author: Jane Smith
:license: Apache-2.0

== Build Settings

* Minimum Python version: 3.9
* Build backend: setuptools
* Include packages: src/myapp

Output TOML file (project-info.toml):

[project]
name = "myapp"
version = "3.2.1"
author = "Jane Smith"
license = "Apache-2.0"

[build-system]
requires = ["setuptools"]
python_requires = ">=3.9"
packages = ["src/myapp"]

Example 2: Server Configuration Document

Input AsciiDoc file (server-config.adoc):

== Database Configuration

.Connection Settings
|===
|Parameter |Value

|Host |db.example.com
|Port |5432
|Database |production
|SSL Mode |require
|Pool Size |20
|===

Output TOML file (server-config.toml):

[database]
host = "db.example.com"
port = 5432
database = "production"
ssl_mode = "require"
pool_size = 20

Example 3: CI/CD Pipeline Settings

Input AsciiDoc file (pipeline.adoc):

= CI/CD Pipeline Configuration

== Stages

. Lint and format check
. Unit tests
. Integration tests
. Build artifact
. Deploy to staging

== Environment Variables

* APP_ENV: production
* LOG_LEVEL: info
* MAX_RETRIES: 3

Output TOML file (pipeline.toml):

[pipeline]
stages = [
  "Lint and format check",
  "Unit tests",
  "Integration tests",
  "Build artifact",
  "Deploy to staging"
]

[environment]
APP_ENV = "production"
LOG_LEVEL = "info"
MAX_RETRIES = 3

Frequently Asked Questions (FAQ)

Q: What is TOML format?

A: TOML (Tom's Obvious Minimal Language) is a configuration file format created by Tom Preston-Werner in 2013. It uses key-value pairs organized into sections (tables) with strong typing for strings, integers, floats, booleans, dates, arrays, and nested tables. TOML is designed to be unambiguous and easy to read, making it ideal for configuration files.

Q: How does AsciiDoc content map to TOML structure?

A: AsciiDoc document attributes (e.g., :key: value) map directly to TOML key-value pairs. Sections (headings) become TOML tables (sections). Tables in AsciiDoc become arrays of tables or nested key-value pairs. Lists can be converted to TOML arrays. The converter analyzes the document structure to produce the most logical TOML representation.

Q: Is TOML better than YAML for configuration?

A: TOML and YAML serve similar purposes but differ in philosophy. TOML is simpler, with fewer edge cases and unambiguous parsing rules. YAML supports more complex structures like references and anchors. TOML is preferred in Rust and modern Python projects, while YAML dominates in Kubernetes and DevOps. Choose based on your ecosystem requirements.

Q: Can TOML handle complex nested data from AsciiDoc?

A: TOML supports nested tables using dotted keys (e.g., [server.database]) or inline tables. However, deeply nested structures (more than 3-4 levels) can become verbose in TOML compared to YAML or JSON. For very complex hierarchical data, consider whether TOML is the most appropriate target format for your use case.

Q: Which programming languages support TOML?

A: TOML has parser libraries for all major languages. Python includes tomllib in the standard library since version 3.11. Rust has the toml crate with first-class support. JavaScript, Go, Java, C#, Ruby, and many other languages have well-maintained TOML libraries. The format's formal specification ensures consistent parsing across implementations.

Q: What data types does TOML support?

A: TOML supports strings (basic and literal), integers, floats, booleans (true/false), dates (RFC 3339 format), times, arrays, inline tables, and tables (sections). All values are strongly typed, meaning "42" is a string while 42 is an integer. This strict typing helps prevent configuration errors that are common in loosely-typed formats.

Q: Where is TOML commonly used?

A: TOML is widely used in Rust projects (Cargo.toml), Python packaging (pyproject.toml), Hugo static site generator (config.toml), Netlify deployment (netlify.toml), and many other tools. Its adoption continues to grow as developers appreciate its clarity and unambiguous parsing compared to alternatives like YAML or INI files.

Q: Are comments preserved in the TOML output?

A: The converter generates TOML with comments derived from AsciiDoc context where appropriate, such as section descriptions becoming TOML comments. TOML natively supports comments using the # prefix, making the output well-documented and maintainable. Any descriptive text from the AsciiDoc source that provides context for configuration values can be included as comments.