Convert Properties to AsciiDoc

Why Convert Properties to AsciiDoc?

Converting Java Properties files to AsciiDoc produces comprehensive, professionally formatted configuration documentation from raw key-value data. While .properties files are perfect for machines to read, they lack the structure and context that humans need to understand complex application configurations. AsciiDoc bridges this gap by providing rich semantic markup that turns cryptic property keys into well-documented reference guides.

AsciiDoc excels at documenting properties files because its definition list syntax (key:: value) is a natural fit for key-value data. Complex configurations with dozens of dotted properties can be broken into logical sections with headers, each section containing a table or definition list with property names, values, defaults, and descriptions. This structured approach is vastly superior to reading raw .properties files for onboarding or troubleshooting.

The multi-format publishing capability of AsciiDoc is especially valuable for configuration documentation. A single AsciiDoc source can produce an HTML reference for your internal wiki, a PDF handbook for distribution to operations teams, and DocBook XML for inclusion in larger product documentation. This single-source approach eliminates the maintenance burden of keeping multiple documentation formats in sync.

AsciiDoc's conditional content feature (ifdef/ifndef) is particularly powerful for properties documentation. You can create a single document that shows different configurations based on the target environment (development, staging, production) or deployment profile. Combined with document attributes, this enables parameterized documentation templates that adapt to different contexts while maintaining a single source of truth.

Key Benefits of Converting Properties to AsciiDoc:

• Definition Lists: Properties map naturally to AsciiDoc's key:: value definition list syntax
• Namespace Grouping: Dotted property hierarchies become organized document sections
• Multi-Format Publishing: One source produces HTML, PDF, EPUB, and DocBook output
• Conditional Content: Show environment-specific configuration using ifdef/ifndef
• Admonition Blocks: Highlight sensitive settings, defaults, and usage warnings
• Document Composition: Use include directives to assemble modular config docs
• Platform Rendering: GitHub, GitLab, and Antora render AsciiDoc natively

Practical Examples

Example 1: Microservice Configuration Documentation

Input Properties file (application.properties):

# Service Discovery
eureka.client.service-url.defaultZone=http://eureka:8761/eureka/
eureka.instance.prefer-ip-address=true
# Circuit Breaker
resilience4j.circuitbreaker.instances.userService.failure-rate-threshold=50
resilience4j.circuitbreaker.instances.userService.wait-duration-in-open-state=60s
resilience4j.circuitbreaker.instances.userService.sliding-window-size=10

Output AsciiDoc file (microservice-config.asciidoc):

= Microservice Configuration Guide
:toc: left
:icons: font
:sectnums:

== Service Discovery (Eureka)

|===
| Property | Value | Description

| `eureka.client.service-url.defaultZone`
| `http://eureka:8761/eureka/`
| Eureka server endpoint

| `eureka.instance.prefer-ip-address`
| `true`
| Register with IP instead of hostname
|===

== Circuit Breaker (Resilience4j)

=== userService Instance

|===
| Setting | Value | Description
| Failure Rate Threshold | 50% | Opens circuit at 50% failure rate
| Wait Duration (Open) | 60s | Time before half-open attempt
| Sliding Window Size | 10 | Number of calls to evaluate
|===

TIP: Adjust `failure-rate-threshold` based on the
criticality of the downstream service.

Example 2: Multi-Environment Configuration

Input Properties file (application-prod.properties):

# Production Cache Settings
spring.cache.type=redis
spring.redis.host=redis-cluster.internal
spring.redis.port=6379
spring.redis.password=${REDIS_PASSWORD}
spring.redis.timeout=2000
spring.cache.redis.time-to-live=3600000

Output AsciiDoc file (prod-cache-config.asciidoc):

= Production Cache Configuration
:toc:
:env: production

== Cache Provider

spring.cache.type:: `redis`

== Redis Connection

[cols="2,2,1"]
|===
| Property | Value | Notes

| `spring.redis.host`
| `redis-cluster.internal`
| Internal DNS name

| `spring.redis.port`
| `6379`
| Default Redis port

| `spring.redis.password`
| `${REDIS_PASSWORD}`
| From secrets manager

| `spring.redis.timeout`
| `2000` (ms)
| Connection timeout
|===

WARNING: The Redis password must be injected via
environment variable. Never hardcode credentials.

== Cache TTL

spring.cache.redis.time-to-live:: `3600000` ms (1 hour)

IMPORTANT: Ensure TTL aligns with data freshness
requirements for your service.

Example 3: Logging Framework Configuration

Input Properties file (log4j2.properties):

# Root logger
rootLogger.level=info
rootLogger.appenderRef.console.ref=ConsoleAppender
# Console appender
appender.console.type=Console
appender.console.name=ConsoleAppender
appender.console.layout.type=PatternLayout
appender.console.layout.pattern=%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg%n

Output AsciiDoc file (logging-config.asciidoc):

= Log4j2 Configuration Reference
:toc:
:source-highlighter: highlight.js

== Root Logger

rootLogger.level:: `info`
rootLogger.appenderRef.console.ref:: `ConsoleAppender`

== Appenders

=== ConsoleAppender

|===
| Property | Value
| Type | Console
| Name | ConsoleAppender
| Layout Type | PatternLayout
|===

==== Log Pattern

[source]
----
%d{yyyy-MM-dd HH:mm:ss} [%t] %-5level %logger{36} - %msg%n
----

|===
| Token | Meaning
| `%d{...}` | Timestamp (yyyy-MM-dd HH:mm:ss)
| `%t` | Thread name
| `%-5level` | Log level (left-padded)
| `%logger{36}` | Logger name (max 36 chars)
| `%msg%n` | Message + newline
|===

NOTE: This pattern provides a readable log format
suitable for both console and file output.

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 documents. The .adoc extension is shorter and more commonly used in modern projects, while .asciidoc is the full-name variant. Both are processed identically by Asciidoctor. The .asc extension is also supported but less common.

Q: How does AsciiDoc compare to Markdown for configuration documentation?

A: AsciiDoc offers several advantages over Markdown for configuration documentation: better table support with column width control, definition lists ideal for key-value data, admonition blocks for warnings and tips, include directives for modular documentation, and conditional content with ifdef. For simple configs Markdown suffices, but for complex enterprise documentation AsciiDoc is superior.

Q: Can the converter handle Spring Boot profile-specific properties?

A: Yes, the converter processes any valid .properties file regardless of its naming convention. Files named application-dev.properties, application-prod.properties, or bootstrap.properties are all handled correctly. The profile context is preserved in the AsciiDoc output as document metadata or section headers.

Q: How are Unicode escape sequences handled?

A: Properties files use \uXXXX escape sequences for non-Latin characters. The converter decodes these sequences into their actual Unicode characters in the AsciiDoc output, since AsciiDoc natively supports UTF-8 encoding. This means internationalized values display correctly in the generated documentation.

Q: Can I use the AsciiDoc output in a Spring REST Docs project?

A: Absolutely. Spring REST Docs generates AsciiDoc snippets by default, so the converted configuration documentation integrates seamlessly with your existing API documentation. You can use include directives to pull the configuration reference into your REST Docs project, creating unified API and configuration documentation.

Q: What happens to empty values and blank lines?

A: Empty property values (e.g., key=) are preserved and documented as empty strings in the AsciiDoc output. Blank lines from the original file are used as section boundaries when grouping related properties. This preserves the logical structure that developers intended in the original .properties file.

Q: Does the converter support the XML variant of Properties files?

A: This converter handles the standard text-based .properties format. For XML-based properties files (the format supported by Properties.loadFromXML()), use the XML to AsciiDoc converter instead. The text-based format with key=value syntax is by far the most common in practice.

Q: How can I automate Properties to AsciiDoc conversion in my CI/CD pipeline?

A: You can integrate this conversion into your build pipeline by calling the conversion API programmatically. This enables automatic documentation generation whenever configuration files change, ensuring your documentation stays in sync with your actual configuration. Combine this with Asciidoctor in your build to produce HTML/PDF output.