Convert AsciiDoc to YML

Why Convert AsciiDoc to YML?

Converting AsciiDoc to YML produces configuration files with the .yml extension, which is the conventional extension used by many popular frameworks and tools. While .yml and .yaml are functionally identical, certain ecosystems have established strong conventions around the .yml extension. Ruby on Rails uses database.yml and routes.yml, Docker Compose uses docker-compose.yml, Travis CI expects .travis.yml, and GitHub Actions uses workflow .yml files. Converting directly to .yml ensures your output files match these expectations without requiring a rename.

The .yml extension gained widespread popularity through Ruby on Rails, which adopted it as the standard configuration file extension in 2005. Since then, it has become the dominant extension in many developer ecosystems. Spring Boot applications use application.yml, Jekyll sites use _config.yml, and Ansible commonly uses .yml for playbooks. When your AsciiDoc documentation describes configuration parameters for these systems, converting to .yml produces immediately usable files.

The conversion process extracts structured data from AsciiDoc documents and maps it to YAML's indentation-based hierarchy. Section headings become top-level keys, nested sections become indented sub-keys, lists convert to YAML sequences, and key-value pairs from tables and definition lists become YAML mappings. The converter handles YAML's strict indentation requirements (spaces only, no tabs) and properly quotes strings that could be misinterpreted as other data types.

This conversion is particularly useful for development teams that maintain infrastructure documentation alongside their codebase. By authoring in AsciiDoc and converting to .yml, teams can generate configuration files that feed directly into their deployment toolchains. This documentation-driven approach reduces configuration drift and ensures that deployment settings remain consistent with their documented specifications.

Key Benefits of Converting AsciiDoc to YML:

• Framework Convention: .yml is expected by Rails, Spring Boot, Jekyll, and more
• Docker Compose: Generate docker-compose.yml from documented service specs
• CI/CD Pipelines: Create Travis CI, GitHub Actions, and GitLab CI configurations
• Human Readable: Clean indentation-based syntax easy to review
• Data Type Support: Proper handling of strings, numbers, booleans, and nulls
• Comment Preservation: Descriptive context maintained as YAML comments
• Ecosystem Compatibility: Works with all YAML parsers across all languages

Practical Examples

Example 1: Docker Compose Service Documentation

Input AsciiDoc file (services.adoc):

= Microservices Architecture

== Web Application

* Image: webapp:latest
* Ports: 80:8080
* Restart Policy: always

== Redis Cache

* Image: redis:7-alpine
* Ports: 6379:6379
* Volume: redis-data:/data

== PostgreSQL Database

* Image: postgres:15
* Ports: 5432:5432
* Environment:
  - POSTGRES_DB: myapp
  - POSTGRES_USER: admin

Output YML file (services.yml):

web_application:
  image: "webapp:latest"
  ports:
    - "80:8080"
  restart: always

redis_cache:
  image: "redis:7-alpine"
  ports:
    - "6379:6379"
  volumes:
    - "redis-data:/data"

postgresql_database:
  image: "postgres:15"
  ports:
    - "5432:5432"
  environment:
    POSTGRES_DB: myapp
    POSTGRES_USER: admin

Example 2: Rails Database Configuration

Input AsciiDoc file (db-config.adoc):

== Database Environments

=== Development

* Adapter: postgresql
* Database: myapp_development
* Host: localhost
* Pool: 5

=== Test

* Adapter: postgresql
* Database: myapp_test
* Host: localhost
* Pool: 5

=== Production

* Adapter: postgresql
* Database: myapp_production
* Host: db.production.internal
* Pool: 25

Output YML file (db-config.yml):

development:
  adapter: postgresql
  database: myapp_development
  host: localhost
  pool: 5

test:
  adapter: postgresql
  database: myapp_test
  host: localhost
  pool: 5

production:
  adapter: postgresql
  database: myapp_production
  host: db.production.internal
  pool: 25

Example 3: GitHub Actions Workflow Spec

Input AsciiDoc file (workflow.adoc):

= CI Workflow Documentation

== Workflow Details

* Name: Build and Test
* Trigger: push to main

== Job Configuration

* Runs On: ubuntu-latest
* Python Version: 3.11

== Steps

. Checkout repository
. Set up Python
. Install dependencies
. Run linting
. Execute test suite

Output YML file (workflow.yml):

name: "Build and Test"
on:
  push:
    branches:
      - main

jobs:
  build:
    runs_on: ubuntu-latest
    python_version: "3.11"
    steps:
      - "Checkout repository"
      - "Set up Python"
      - "Install dependencies"
      - "Run linting"
      - "Execute test suite"

Frequently Asked Questions (FAQ)

Q: What is the difference between .yml and .yaml?

A: There is no functional difference between .yml and .yaml files. Both use identical YAML syntax and are processed by the same parsers. The .yml extension originated from the three-letter file extension convention and was popularized by Ruby on Rails. The .yaml extension is the officially recommended extension by the YAML specification. Use .yml when your framework or tooling expects it.

Q: Which tools prefer the .yml extension?

A: Several popular tools use .yml by convention: Ruby on Rails (database.yml, routes.yml), Docker Compose (docker-compose.yml), Travis CI (.travis.yml), GitHub Actions (.github/workflows/*.yml), Spring Boot (application.yml), Jekyll (_config.yml), and Symfony (services.yml). Using .yml ensures your files match these ecosystem expectations.

Q: How does the converter handle AsciiDoc formatting?

A: Since YML is a data format, text formatting from AsciiDoc (bold, italic, code) is stripped during conversion. Only the textual content is preserved as string values. The document's hierarchical structure (sections and nesting) is mapped to YAML's indentation-based hierarchy. Multi-line text is handled using YAML's block scalar notation (| for literal or > for folded style).

Q: Can I use the YML output with Docker Compose?

A: The YML output provides a structured representation of your service configuration that can be adapted for Docker Compose. Docker Compose requires specific top-level keys (version, services, volumes, networks) and service-specific properties. The converted YML captures your configuration data which can be organized into the Docker Compose schema with minor adjustments.

Q: How are AsciiDoc tables converted to YML?

A: AsciiDoc tables are converted to either YAML sequences of mappings (for multi-column tables) or simple key-value mappings (for two-column key-value tables). The converter analyzes the table structure to determine the most appropriate YAML representation. Headers become keys, and data rows become values or list items within the YAML hierarchy.

Q: Is indentation critical in YML files?

A: Yes, indentation is the primary structural mechanism in YAML/YML. Incorrect indentation will cause parsing errors or incorrect data hierarchy. The converter always produces properly indented output using 2-space indentation (the most common convention). Only space characters are used for indentation, never tabs, as YAML explicitly forbids tab characters for this purpose.

Q: What data types are supported in the YML output?

A: The YML output uses proper YAML data types: strings (quoted when needed), integers (42), floats (3.14), booleans (true/false), null values, and dates. Arrays are represented as sequences (- item), and objects as mappings (key: value). The converter detects appropriate types from AsciiDoc content and avoids YAML's implicit type coercion issues by quoting ambiguous values.

Q: Can I validate the YML output?

A: Yes, you can validate the YML output using YAML linters such as yamllint, online YAML validators, or IDE plugins. For framework-specific validation, tools like kubeval (Kubernetes), docker-compose config (Docker Compose), and ansible-lint (Ansible) check both YAML syntax and schema compliance. The converter produces syntactically valid YAML that passes standard validation checks.