Convert AsciiDoc to Properties

Why Convert AsciiDoc to Properties?

Converting AsciiDoc to Properties format is useful when you need to extract structured data from technical documentation and transform it into application configuration files. AsciiDoc documents often contain configuration examples, parameter lists, and settings tables that can be directly translated into Properties format for use in Java applications, Spring Boot projects, or other JVM-based systems.

AsciiDoc, created by Stuart Rackham in 2002, is a powerful lightweight markup language designed for writing technical documentation. It supports rich formatting including tables, code blocks, admonitions, and cross-references. Properties files, on the other hand, are deliberately simple key-value stores that Java applications load at runtime using the java.util.Properties class. This conversion bridges the gap between documentation and deployable configuration.

The Properties format has been part of the Java ecosystem since JDK 1.0 in 1995 and remains the default configuration mechanism for countless Java applications, including Spring Boot (application.properties), Apache projects, and build tools like Maven and Gradle. Converting documentation into Properties files enables rapid configuration deployment and ensures that documented settings match actual application parameters.

This conversion is particularly valuable in DevOps and documentation-as-code workflows where teams maintain configuration documentation in AsciiDoc format alongside their source code. By converting directly to Properties, teams can ensure consistency between documentation and deployed configurations, reducing the risk of configuration drift and simplifying the deployment pipeline.

Key Benefits of Converting AsciiDoc to Properties:

• Configuration Extraction: Pull settings from documented parameters into deployable config files
• Java Ecosystem: Native support in all JVM applications via java.util.Properties
• Spring Boot Ready: Direct use as application.properties in Spring projects
• Documentation Sync: Keep config files aligned with technical documentation
• Simple Format: Properties files are easy to read, edit, and parse
• DevOps Friendly: Integrate into CI/CD pipelines for automated configuration
• Widely Supported: Properties files work across Java, Python, Ruby, and Node.js

Practical Examples

Example 1: Database Configuration Documentation

Input AsciiDoc file (db-config.adoc):

= Database Configuration Guide

== Connection Settings

The following parameters configure the database connection:

|===
| Parameter | Value | Description

| db.host | localhost | Database server hostname
| db.port | 5432 | PostgreSQL default port
| db.name | myapp_prod | Production database name
| db.pool.size | 20 | Connection pool size
|===

Output Properties file (db-config.properties):

# Database Configuration Guide
# Connection Settings
db.host=localhost
db.port=5432
db.name=myapp_prod
db.pool.size=20

Example 2: Application Settings Manual

Input AsciiDoc file (app-settings.adoc):

= Application Settings Reference
:version: 2.5.0

== Server Configuration

* `server.port` = 8080
* `server.context-path` = /api
* `server.compression.enabled` = true

== Logging

* `logging.level.root` = WARN
* `logging.level.com.myapp` = DEBUG
* `logging.file.name` = app.log

Output Properties file (app-settings.properties):

# Application Settings Reference v2.5.0
# Server Configuration
server.port=8080
server.context-path=/api
server.compression.enabled=true
# Logging
logging.level.root=WARN
logging.level.com.myapp=DEBUG
logging.file.name=app.log

Example 3: Internationalization Resource

Input AsciiDoc file (i18n-guide.adoc):

= Localization Strings Reference

== UI Labels

The following strings are used in the application UI:

* `ui.button.submit` -- "Submit Form"
* `ui.button.cancel` -- "Cancel"
* `ui.title.dashboard` -- "Main Dashboard"
* `ui.message.welcome` -- "Welcome, {0}!"
* `ui.error.notfound` -- "Page not found"

Output Properties file (messages.properties):

# Localization Strings Reference
# UI Labels
ui.button.submit=Submit Form
ui.button.cancel=Cancel
ui.title.dashboard=Main Dashboard
ui.message.welcome=Welcome, {0}!
ui.error.notfound=Page not found

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc format?

A: AsciiDoc is a lightweight markup language created by Stuart Rackham in 2002 for authoring technical documentation. It uses plain text with intuitive formatting conventions such as = for headings, * for bold, and | for tables. AsciiDoc files can be processed by tools like Asciidoctor to produce HTML, PDF, EPUB, and other output formats. It is popular in open-source projects, software documentation, and book publishing.

Q: What is a Properties file?

A: A Properties file is a simple text-based configuration format that stores data as key=value pairs, one per line. Originating from the Java ecosystem (java.util.Properties class), it supports comments with # or !, multi-line values using backslash continuation, and Unicode escape sequences. Properties files are the standard configuration mechanism for Java applications, Spring Boot, Apache projects, and many build tools.

Q: How does the conversion handle AsciiDoc formatting?

A: The converter extracts text content from AsciiDoc markup, stripping formatting syntax like bold markers, heading indicators, and table delimiters. Structured content such as definition lists and tables with key-value patterns are mapped to Properties key=value pairs. Section headings become comment lines to preserve document organization. Complex elements like images and code blocks are converted to descriptive comments.

Q: Can Properties files handle nested data structures?

A: Properties files are inherently flat, but nesting is conventionally simulated using dotted key notation (e.g., database.connection.host=localhost). This convention is widely supported by frameworks like Spring Boot, which automatically maps dotted keys to nested configuration objects. The conversion preserves any hierarchical structure from AsciiDoc headings using this dotted namespace approach.

Q: Will special characters be preserved in the Properties output?

A: Yes. Properties files support Unicode characters through escape sequences (e.g., \u00E9 for accented characters). The converter properly escapes special characters that have meaning in Properties syntax, including =, :, and leading whitespace. Line breaks within values are handled using backslash continuation. AsciiDoc Unicode content is preserved correctly in the output.

Q: Is this conversion useful for Spring Boot projects?

A: Absolutely. Spring Boot uses application.properties as its primary configuration file. If your AsciiDoc documentation contains Spring Boot configuration parameters, converting it directly to Properties format creates a ready-to-use configuration file. This is particularly helpful when setting up new environments based on documented specifications or when migrating configurations documented in technical manuals.

Q: What happens to AsciiDoc tables during conversion?

A: AsciiDoc tables with key-value patterns (two-column tables where the first column represents parameter names) are converted into corresponding Properties entries. Multi-column tables are flattened, with additional columns added as comments or concatenated values. Tables containing purely descriptive content are converted to comment blocks to maintain context in the output file.

Q: Can I convert Properties back to AsciiDoc?

A: Yes, our converter also supports Properties to AsciiDoc conversion. This reverse process creates structured AsciiDoc documentation from Properties files, organizing keys by their namespace hierarchy into sections and generating tables for related configuration groups. This is useful for automatically generating configuration reference documentation from existing Properties files.