Convert TOML to ASCIIDOC

Why Convert TOML to ASCIIDOC?

Converting TOML to AsciiDoc is essential for teams that need to incorporate configuration details into comprehensive technical documentation. While TOML is excellent for machine-parseable configuration, AsciiDoc transforms that data into professionally formatted documentation that can be published in multiple formats including HTML, PDF, and EPUB.

AsciiDoc is the preferred documentation format for many enterprise projects and open-source organizations because of its advanced features: conditional content processing, document includes, complex table layouts, and semantic markup. Converting TOML configuration files to AsciiDoc allows you to create complete configuration reference guides that integrate seamlessly with existing documentation systems.

This conversion is particularly valuable in CI/CD documentation pipelines. When your project configuration changes in Cargo.toml or pyproject.toml, the converted AsciiDoc documentation can be automatically regenerated and published as part of your documentation build process, ensuring that configuration references always stay current.

AsciiDoc's support for attributes, includes, and conditional processing means you can create dynamic configuration documentation that adapts based on the target audience or deployment environment. This flexibility is impossible with raw TOML files but becomes straightforward once the data is in AsciiDoc format.

Key Benefits of Converting TOML to ASCIIDOC:

• Enterprise Documentation: Create publication-grade configuration references
• CI/CD Integration: Auto-generate config docs in build pipelines
• Multiple Outputs: Publish as HTML, PDF, EPUB, or DocBook from one source
• Semantic Structure: Rich headings, tables, and admonitions for clarity
• Include Directives: Embed configuration docs in larger documentation sets
• Conditional Content: Show different config details per environment
• Platform Rendering: GitHub and GitLab render AsciiDoc files natively

Practical Examples

Example 1: Cargo Configuration Documentation

Input TOML file (Cargo.toml):

[package]
name = "http-proxy"
version = "3.2.1"
edition = "2021"
license = "MIT OR Apache-2.0"
repository = "https://github.com/example/http-proxy"

[dependencies]
hyper = { version = "1.0", features = ["http1", "server"] }
tokio = { version = "1.32", features = ["full"] }

[profile.release]
opt-level = 3
lto = true

Output ASCIIDOC file (Cargo.asciidoc):

= HTTP-Proxy Configuration Reference
:toc: left
:icons: font

== Package Metadata

.Package Information
|===
| Property | Value

| Name | http-proxy
| Version | 3.2.1
| Edition | 2021
| License | MIT OR Apache-2.0
| Repository | https://github.com/example/http-proxy
|===

== Dependencies

.Required Crates
|===
| Crate | Version | Features

| hyper | 1.0 | http1, server
| tokio | 1.32 | full
|===

== Release Profile

NOTE: Release builds use maximum optimization.

* Optimization Level: 3 (maximum)
* Link-Time Optimization: enabled

Example 2: Hugo Site Configuration

Input TOML file (hugo.toml):

baseURL = "https://example.com/"
languageCode = "en-us"
title = "My Technical Blog"
theme = "paper"

[params]
author = "Jane Developer"
description = "Notes on software engineering"
showReadingTime = true

[menu]
[[menu.main]]
name = "Home"
url = "/"
weight = 1

[[menu.main]]
name = "Posts"
url = "/posts/"
weight = 2

Output ASCIIDOC file (hugo.asciidoc):

= Hugo Site Configuration
:author: Jane Developer

== General Settings

|===
| Setting | Value
| Base URL | https://example.com/
| Language | en-us
| Title | My Technical Blog
| Theme | paper
|===

== Site Parameters

* Author: Jane Developer
* Description: Notes on software engineering
* Show Reading Time: true

== Navigation Menu

.Main Menu Items
|===
| Name | URL | Weight
| Home | / | 1
| Posts | /posts/ | 2
|===

Example 3: Netlify Deployment Configuration

Input TOML file (netlify.toml):

[build]
command = "npm run build"
publish = "dist"

[build.environment]
NODE_VERSION = "18"
NPM_FLAGS = "--legacy-peer-deps"

[[redirects]]
from = "/old-path"
to = "/new-path"
status = 301

[[headers]]
for = "/*.js"
[headers.values]
Cache-Control = "public, max-age=31536000"

Output ASCIIDOC file (netlify.asciidoc):

= Netlify Deployment Configuration

== Build Settings

|===
| Setting | Value
| Command | `npm run build`
| Publish Directory | `dist`
|===

=== Environment Variables

|===
| Variable | Value
| NODE_VERSION | 18
| NPM_FLAGS | --legacy-peer-deps
|===

== Redirects

|===
| From | To | Status
| /old-path | /new-path | 301 (Permanent)
|===

== Custom Headers

WARNING: Cache headers affect browser caching behavior.

.Headers for `/*.js`
* Cache-Control: `public, max-age=31536000`

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and ASCIIDOC file extensions?

A: Both .adoc and .asciidoc are valid extensions for AsciiDoc files. The .adoc extension is more commonly used as it is shorter, while .asciidoc is the full name extension. Both are processed identically by Asciidoctor and other AsciiDoc tools. GitHub and GitLab recognize both extensions for rendering.

Q: How does TOML differ from YAML for configuration?

A: TOML uses explicit [section] headers and key = value syntax with strict typing, while YAML uses indentation-based nesting. TOML has a formal specification that eliminates parsing ambiguity, whereas YAML's complexity has led to known parsing issues. TOML is generally preferred for simpler configuration, while YAML handles more complex nested structures.

Q: Can I include the converted AsciiDoc in a larger document?

A: Yes! AsciiDoc supports include directives (include::config.asciidoc[]) that let you embed the converted file in a larger document. This is ideal for creating comprehensive project documentation where configuration details are just one section of a bigger reference guide.

Q: How are TOML inline tables represented in AsciiDoc?

A: TOML inline tables like `{version = "1.0", features = ["derive"]}` are expanded into AsciiDoc table rows or description lists, making each key-value pair visible and well-formatted. This improves readability compared to the compact inline TOML notation.

Q: What output formats can I generate from the AsciiDoc file?

A: Using Asciidoctor, you can generate HTML5, PDF (via asciidoctor-pdf), EPUB3 (via asciidoctor-epub3), DocBook 5 XML, and man pages. This makes the converted configuration documentation suitable for web publishing, print distribution, and e-reader formats.

Q: Does the conversion preserve TOML comments?

A: TOML comments (# lines) are preserved in the conversion as AsciiDoc paragraph text or comment blocks. This ensures that explanatory notes in your configuration files become part of the documentation, providing context for each setting.

Q: Can I automate the TOML to AsciiDoc conversion in a CI pipeline?

A: Yes! The conversion can be integrated into CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins) to automatically regenerate configuration documentation whenever TOML files are updated. Combined with Asciidoctor, you can build and deploy updated documentation automatically.

Q: How large can the TOML files be for conversion?

A: Our converter handles TOML files of any practical size. Most configuration files are relatively small (under 100KB), but even larger files with hundreds of sections and thousands of key-value pairs can be converted efficiently. The resulting AsciiDoc file will be proportionally larger due to added formatting markup.