Convert AsciiDoc to INI

Why Convert AsciiDoc to INI?

Converting AsciiDoc to INI is useful when you need to extract structured information from documentation and present it in a simple configuration format. AsciiDoc documents often contain metadata attributes, parameter definitions, and setting descriptions that map directly to INI's section-and-key-value structure. This conversion bridges the gap between human-readable documentation and machine-parseable configuration data.

The INI format, originating from the MS-DOS era, remains one of the most widely used configuration formats in computing. Its simplicity is its strength: [section] headers group related settings, and key=value pairs define individual properties. Python's configparser module, PHP's parse_ini_file(), and countless other language libraries read INI natively, making it a universal choice for application configuration that needs to be both human-editable and machine-readable.

AsciiDoc's document attributes (:key: value syntax) are conceptually identical to INI properties, making the conversion semantically natural. Section headings become INI sections, attribute definitions become key-value pairs, and structured lists can be flattened into property sets. This is particularly valuable when technical documentation serves dual purposes: guiding human readers while also providing extractable configuration data for automated deployment or setup processes.

Teams that maintain both documentation and configuration files can benefit from a single-source approach. By documenting server settings, application parameters, or deployment configurations in AsciiDoc, they can generate both human-readable HTML documentation and machine-readable INI configuration files from the same source. This reduces duplication and ensures that documentation always reflects the actual configuration values in use.

Key Benefits of Converting AsciiDoc to INI:

• Configuration Extraction: Pull settings from documentation into usable config files
• Universal Compatibility: INI is parsed natively by Python, PHP, C#, and more
• Human Readable: INI files are simple enough for anyone to edit
• Section Organization: AsciiDoc headings map naturally to INI sections
• Attribute Mapping: AsciiDoc :key: value syntax translates directly to INI
• Legacy System Support: INI is supported by virtually all platforms
• Single-Source Workflow: Generate both docs and config from one AsciiDoc file

Practical Examples

Example 1: Application Configuration Extraction

Input AsciiDoc file (config-guide.adoc):

= Application Configuration
:app-name: MyWebApp
:version: 3.2.1

== Server

* host = 0.0.0.0
* port = 8080
* workers = 4
* debug = false

== Database

* driver = postgresql
* host = localhost
* port = 5432
* name = myapp_prod

Output INI file (config-guide.ini):

; Application Configuration
; Generated from AsciiDoc source

[metadata]
app-name = MyWebApp
version = 3.2.1

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

[database]
driver = postgresql
host = localhost
port = 5432
name = myapp_prod

Example 2: Deployment Documentation to Config

Input AsciiDoc file (deploy.adoc):

= Deployment Settings
:environment: production

== AWS

Region: us-east-1
Instance type: t3.medium
AMI: ami-0abcdef12345

== Monitoring

Enabled: true
Interval: 60
Alert email: [email protected]

Output INI file (deploy.ini):

; Deployment Settings

[metadata]
environment = production

[aws]
region = us-east-1
instance_type = t3.medium
ami = ami-0abcdef12345

[monitoring]
enabled = true
interval = 60
alert_email = [email protected]

Example 3: Multi-Service Configuration

Input AsciiDoc file (services.adoc):

= Microservices Configuration
:author: Platform Team

== Auth Service

Port: 3001
JWT secret: change-in-production
Token expiry: 3600

== API Gateway

Port: 8000
Rate limit: 1000
Timeout: 30

Output INI file (services.ini):

; Microservices Configuration
; Author: Platform Team

[auth_service]
port = 3001
jwt_secret = change-in-production
token_expiry = 3600

[api_gateway]
port = 8000
rate_limit = 1000
timeout = 30

Frequently Asked Questions (FAQ)

Q: What is INI format?

A: INI (Initialization) is a simple text-based configuration format using [section] headers and key=value pairs. It originated in MS-DOS and Windows but is now used across all platforms. Common examples include php.ini, my.cnf (MySQL), .gitconfig, and setup.cfg (Python). Its simplicity makes it easy to read, write, and parse.

Q: How are AsciiDoc sections mapped to INI sections?

A: AsciiDoc headings (== Section Name) become INI section headers ([section_name]). The heading text is converted to a valid INI section identifier by lowercasing and replacing spaces with underscores. Content within each AsciiDoc section is extracted as key=value pairs under the corresponding INI section.

Q: Can INI files handle nested data?

A: INI natively supports only one level of nesting: sections containing key-value pairs. It does not support nested sections or hierarchical data like JSON or YAML. If your AsciiDoc document has deeply nested sections, lower-level headings may be flattened or combined into section names (e.g., [parent.child]).

Q: What happens to AsciiDoc prose content during conversion?

A: Narrative paragraphs in AsciiDoc do not have a natural INI equivalent since INI is designed for structured key-value data, not prose. During conversion, prose content may be preserved as comments (prefixed with ;) or omitted depending on the converter settings. Structured data like lists and tables convert more naturally to INI properties.

Q: Are AsciiDoc attributes preserved as INI properties?

A: Yes. AsciiDoc document attributes (:key: value) map directly to INI key-value pairs. These are typically placed in a [metadata] or [attributes] section in the INI output. This is one of the most natural mappings between the two formats, as both use a key-value syntax.

Q: Does INI support data types?

A: INI files treat all values as strings by default. There is no formal type system. Applications reading INI files must convert values to appropriate types (integers, booleans, etc.) themselves. Python's configparser, for example, provides getint(), getfloat(), and getboolean() methods for this purpose.

Q: Can I use the generated INI with Python?

A: Yes. Python's standard library includes the configparser module, which reads and writes INI files natively. After conversion, you can load the INI file with configparser.ConfigParser(), access sections with config['section_name'], and retrieve values with config.get('section', 'key'). No additional packages are needed.

Q: How are comments handled in the conversion?

A: AsciiDoc comments (// single-line and ////...block...//// comment blocks) can be preserved as INI comments (prefixed with ; or #). Additionally, descriptive text from the AsciiDoc document may be included as INI comments to provide context for the configuration values. This maintains the documentation value in the output.