Convert TOML to ADOC

Why Convert TOML to ADOC?

Converting TOML configuration files to AsciiDoc format is valuable when you need to document your project's configuration settings in a professional, readable format. TOML files like Cargo.toml or pyproject.toml contain essential project metadata and dependency information that is often needed in technical documentation, user guides, or project wikis.

AsciiDoc excels at presenting structured data in a human-friendly way with features like formatted tables, section headers, admonitions, and cross-references. By converting TOML to ADOC, you can transform raw configuration data into well-organized documentation that includes explanations, context, and visual formatting that makes the information accessible to team members who may not be familiar with TOML syntax.

This conversion is particularly useful in documentation-as-code workflows where project configuration needs to be included in generated documentation. AsciiDoc's ability to produce multiple output formats (HTML, PDF, EPUB) means your converted TOML data can be published alongside other project documentation using tools like Asciidoctor or Antora.

The conversion process maps TOML sections to AsciiDoc headings, key-value pairs to table rows or definition lists, and arrays to formatted lists. Comments in the TOML file can be preserved as descriptive text, creating a self-documenting reference that goes beyond what the raw configuration file provides.

Key Benefits of Converting TOML to ADOC:

• Professional Documentation: Transform configuration data into publication-ready documents
• Multi-Format Output: AsciiDoc can render to HTML, PDF, EPUB, and DocBook
• Structured Presentation: Tables and sections make TOML data easy to navigate
• Documentation Integration: Include config details in project documentation pipelines
• Team Accessibility: Make configuration readable for non-technical team members
• Version Tracking: AsciiDoc works well with version control systems
• Cross-Referencing: Link configuration documentation to other project docs

Practical Examples

Example 1: Rust Project Configuration

Input TOML file (Cargo.toml):

[package]
name = "web-server"
version = "2.1.0"
edition = "2021"
authors = ["Alice Smith <[email protected]>"]
description = "A lightweight HTTP web server"

[dependencies]
tokio = { version = "1.28", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
axum = "0.6"

Output ADOC file (Cargo.adoc):

= Web-Server Configuration
:toc:

== Package Information

|===
| Property | Value
| Name | web-server
| Version | 2.1.0
| Edition | 2021
| Authors | Alice Smith
| Description | A lightweight HTTP web server
|===

== Dependencies

|===
| Crate | Version | Features
| tokio | 1.28 | full
| serde | 1.0 | derive
| axum | 0.6 | -
|===

Example 2: Python Project Metadata

Input TOML file (pyproject.toml):

[project]
name = "data-pipeline"
version = "0.5.0"
requires-python = ">=3.9"

[project.scripts]
pipeline = "data_pipeline.cli:main"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"

Output ADOC file (pyproject.adoc):

= Data-Pipeline Project

== Project Metadata

|===
| Field | Value
| Name | data-pipeline
| Version | 0.5.0
| Python Required | >=3.9
|===

== Scripts

* `pipeline` -> `data_pipeline.cli:main`

== Testing Configuration (pytest)

* Test paths: `tests`
* Options: `-v --tb=short`

Example 3: Application Settings

Input TOML file (config.toml):

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

[database]
url = "postgresql://localhost/mydb"
max_connections = 20
timeout = 30

[[routes]]
path = "/api/v1"
handler = "api_handler"

[[routes]]
path = "/health"
handler = "health_check"

Output ADOC file (config.adoc):

= Application Configuration

== Server Settings

|===
| Setting | Value
| Host | 0.0.0.0
| Port | 8080
| Workers | 4
|===

== Database Settings

|===
| Setting | Value
| URL | postgresql://localhost/mydb
| Max Connections | 20
| Timeout | 30
|===

== Routes

[cols="1,1"]
|===
| Path | Handler
| /api/v1 | api_handler
| /health | health_check
|===

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, co-founder of GitHub. It uses key = value pairs organized in [sections] with strictly typed values including strings, integers, floats, booleans, dates, arrays, and tables. It is widely used in Rust (Cargo.toml), Python (pyproject.toml), and other ecosystems.

Q: What is ADOC (AsciiDoc) format?

A: AsciiDoc is a lightweight markup language designed for writing documentation, books, and articles. It supports rich formatting features like tables, code blocks with syntax highlighting, admonitions, cross-references, and can be converted to multiple output formats including HTML, PDF, EPUB, and DocBook using the Asciidoctor processor.

Q: How are TOML sections represented in AsciiDoc?

A: TOML [section] headers are converted to AsciiDoc section headings (== Section). Nested sections like [section.subsection] become nested headings. Key-value pairs within sections are typically presented as AsciiDoc tables or definition lists for clear, structured presentation.

Q: Are TOML data types preserved in the conversion?

A: AsciiDoc is a text-based documentation format without native data types. TOML types (strings, numbers, booleans, dates) are converted to their string representations in the AsciiDoc output. The structure and hierarchy of the data is preserved through headings, tables, and lists.

Q: Can I convert TOML arrays to AsciiDoc lists?

A: Yes! TOML arrays are converted to AsciiDoc bulleted or numbered lists, depending on the context. Array of tables ([[section]]) are converted to structured tables or repeated sections. Inline arrays are presented as comma-separated values or individual list items.

Q: What tools can render the resulting ADOC file?

A: The resulting AsciiDoc file can be rendered using Asciidoctor (Ruby, Java, or JavaScript versions), GitHub and GitLab (which natively render .adoc files), IDE plugins for IntelliJ IDEA and VS Code, and documentation platforms like Antora. You can generate HTML, PDF, EPUB, and other formats from the converted file.

Q: Is the conversion reversible?

A: Converting AsciiDoc back to TOML is generally not practical because AsciiDoc is a documentation format with formatting that does not map to TOML's strict key-value structure. It is recommended to keep the original TOML file as the source of truth and use the AsciiDoc version for documentation purposes only.

Q: How are TOML comments handled during conversion?

A: TOML comments (lines starting with #) can be converted to descriptive text or AsciiDoc comments (// comment) in the output. This allows you to preserve documentation context that was included in the original configuration file, making the resulting document more informative.