Convert Properties to ADOC

Why Convert Properties to ADOC?

Converting Java Properties files to AsciiDoc format transforms flat key-value configuration data into professional, well-organized documentation. Properties files are essential for Java and Spring Boot applications, but their simple key=value structure makes them difficult to present in configuration guides, onboarding documentation, or architecture reviews. AsciiDoc provides the semantic structure needed to turn configuration data into readable, navigable reference documents.

AsciiDoc is particularly well-suited for properties conversion because of its powerful table support and definition lists. Dotted property namespaces like app.datasource.url can be organized into hierarchical sections with headers, while property groups become structured tables with key, value, and description columns. This organization makes configuration documentation far more accessible than scanning raw .properties files.

One of AsciiDoc's greatest strengths is its ability to produce multiple output formats from a single source. Once your properties data is in AsciiDoc format, you can generate HTML configuration guides for your wiki, PDF reference documents for distribution, or DocBook XML for integration into larger documentation systems. This makes AsciiDoc an excellent format for maintaining living configuration documentation.

For teams using documentation-as-code practices, AsciiDoc configuration references integrate seamlessly with Git-based workflows. As Spring Boot application.properties files evolve, the corresponding AsciiDoc documentation can be updated and versioned alongside the source code. Platforms like GitHub, GitLab, and Antora render AsciiDoc natively, making configuration docs immediately available to the team.

Key Benefits of Converting Properties to ADOC:

• Structured Tables: Organize key-value pairs into formatted tables with descriptions
• Hierarchical Sections: Group dotted property namespaces into logical document sections
• Multi-Format Output: Generate HTML, PDF, EPUB, and DocBook from one source
• Admonition Blocks: Highlight important configuration notes, warnings, and tips
• Table of Contents: Auto-generated navigation for large configuration references
• Code Block Formatting: Preserve original properties syntax with highlighting
• Version Control Friendly: Plain text format works seamlessly with Git workflows

Practical Examples

Example 1: Spring Boot Database Configuration

Input Properties file (application.properties):

# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/appdb
spring.datasource.username=app_user
spring.datasource.password=${DB_PASSWORD}
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.minimum-idle=5
spring.jpa.hibernate.ddl-auto=validate

Output ADOC file (database-config.adoc):

= Database Configuration Reference
:toc: left
:icons: font
:source-highlighter: highlight.js

== DataSource Settings

|===
| Property | Value | Description

| `spring.datasource.url`
| `jdbc:postgresql://localhost:5432/appdb`
| JDBC connection URL for PostgreSQL

| `spring.datasource.username`
| `app_user`
| Database connection username

| `spring.datasource.password`
| `${DB_PASSWORD}`
| Database password (environment variable)
|===

WARNING: Never commit plain-text passwords. Use environment variables or a secrets manager.

== Connection Pool (HikariCP)

|===
| Property | Value
| `maximum-pool-size` | 20
| `minimum-idle` | 5
|===

== JPA / Hibernate

spring.jpa.hibernate.ddl-auto:: `validate` (schema validation only)

Example 2: Server and Logging Configuration

Input Properties file (application.properties):

# Server settings
server.port=8443
server.ssl.enabled=true
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-type=PKCS12
# Logging
logging.level.root=WARN
logging.level.com.myapp=DEBUG
logging.file.name=/var/log/myapp/application.log

Output ADOC file (server-config.adoc):

= Server & Logging Configuration
:toc:
:sectnums:

== Server Settings

server.port:: `8443`

=== SSL Configuration

IMPORTANT: SSL is enabled. Ensure the keystore file is present at deployment.

|===
| Property | Value
| `server.ssl.enabled` | `true`
| `server.ssl.key-store` | `classpath:keystore.p12`
| `server.ssl.key-store-type` | `PKCS12`
|===

== Logging Configuration

[cols="2,1"]
|===
| Logger | Level
| Root | WARN
| com.myapp | DEBUG
|===

TIP: Set `com.myapp` to `INFO` in production to reduce log volume.

Log output:: `/var/log/myapp/application.log`

Example 3: Internationalization Resource Bundle

Input Properties file (messages_en.properties):

# English locale messages
app.title=My Application
app.welcome=Welcome, {0}!
error.not_found=Page not found
error.forbidden=Access denied
validation.email.invalid=Please enter a valid email
validation.password.length=Password must be at least {0} characters

Output ADOC file (messages-reference.adoc):

= Internationalization Reference (English)
:toc:
:icons: font

== Application Messages

|===
| Key | Message | Parameters

| `app.title` | My Application | None
| `app.welcome` | Welcome, {0}! | {0} = username
|===

== Error Messages

|===
| Key | Message
| `error.not_found` | Page not found
| `error.forbidden` | Access denied
|===

== Validation Messages

|===
| Key | Message | Parameters
| `validation.email.invalid` | Please enter a valid email | None
| `validation.password.length` | Password must be at least {0} characters | {0} = minimum length
|===

NOTE: Placeholders use `java.text.MessageFormat` syntax ({0}, {1}, ...).

Frequently Asked Questions (FAQ)

Q: What is a Java Properties file?

A: A Java Properties file (.properties) is a plain text configuration format that stores data as key-value pairs separated by = or :. It is the standard configuration format in the Java ecosystem, used extensively by Spring Boot, Maven, Gradle, and other JVM frameworks. Lines starting with # or ! are comments.

Q: How are dotted property namespaces handled in AsciiDoc?

A: Dotted namespaces like spring.datasource.url are organized into hierarchical AsciiDoc sections. The top-level namespace becomes a section header (e.g., "== DataSource Settings"), and individual properties are listed in tables or definition lists within that section, creating a clear, navigable structure.

Q: Can I generate PDF configuration guides from the ADOC output?

A: Yes! Use Asciidoctor-PDF to generate professional PDF documents from the converted AsciiDoc file. You can also produce HTML pages, EPUB books, or DocBook XML. This makes AsciiDoc an ideal intermediate format for creating polished configuration reference documentation.

Q: Are comments from the Properties file preserved?

A: Yes, comments from the original .properties file are preserved and converted into appropriate AsciiDoc elements. Section comments may become section descriptions, inline comments can be rendered as admonition blocks or notes, and group headers are transformed into section titles.

Q: How does this handle Spring Boot placeholder syntax?

A: Spring Boot placeholders like ${DB_PASSWORD} and ${server.port:8080} are preserved as-is in the AsciiDoc output. They are rendered in monospace font within tables, and the converter can add notes explaining that these values are resolved at runtime from environment variables or other property sources.

Q: Can I convert multiple .properties files at once?

A: Yes, you can upload and convert multiple Properties files in a single session. Each file will be converted to its own AsciiDoc document. This is useful for generating documentation for environment-specific configurations (application-dev.properties, application-prod.properties).

Q: Does the converter handle multi-line property values?

A: Yes, multi-line values using backslash continuation (common in Properties files) are properly handled. The full value is reconstructed and displayed in the AsciiDoc output, typically within a code block or as a complete table cell value.

Q: Where can I render AsciiDoc files?

A: AsciiDoc files render natively on GitHub and GitLab. You can also use Asciidoctor (Ruby, Java, or JavaScript versions), VS Code with the AsciiDoc extension, IntelliJ IDEA, or online tools like asciidoclive.com. For documentation sites, Antora provides a full publishing pipeline.