Convert ADOC to YAML

Why Convert ADOC to YAML?

Converting AsciiDoc to YAML transforms structured documentation into a human-readable data format that is essential for modern DevOps workflows, configuration management, and automation. While AsciiDoc excels at creating rich documentation, YAML provides the clean, hierarchical structure needed for configuration files, infrastructure as code, and data serialization.

YAML has become the de facto standard for configuration in cloud-native technologies like Kubernetes, Docker Compose, and CI/CD platforms. By converting AsciiDoc content to YAML, you can bridge the gap between documentation and implementation, enabling automation workflows that consume your documented specifications directly as configuration data.

This conversion is invaluable when you need to extract structured data from documentation or create configuration files from documented specifications. YAML's intuitive key-value syntax maps naturally to AsciiDoc's definition lists, and its list structure aligns perfectly with AsciiDoc bullet points.

The conversion process preserves the hierarchical structure of your AsciiDoc documents, transforming sections into nested YAML mappings and lists into YAML sequences. Document attributes become metadata fields, making it easy to maintain consistency between your documentation and configuration.

Key Benefits of Converting ADOC to YAML:

• DevOps Integration: YAML is native to Kubernetes, Docker, Ansible, and major CI/CD platforms
• Human-Readable Configuration: Clean syntax makes files easy to read and maintain
• Data Structure Preservation: Hierarchies and lists map naturally to YAML format
• Automation-Ready Format: YAML files can be consumed directly by automation tools
• Version Control Friendly: Plain text format works excellently with Git
• Cross-Platform Compatibility: YAML parsers available in every major language
• Documentation to Configuration Pipeline: Convert specs into actionable config files

Practical Examples

Example 1: Service Configuration Documentation

Input ADOC file (config.adoc):

= Web Application Configuration
:author: DevOps Team

== Application Settings

Application name:: my-web-app
Version:: 2.1.0
Environment:: production

== Server Configuration

* Host: 0.0.0.0
* Port: 8080
* Workers: 4

== Database Settings

Connection string:: postgresql://localhost:5432/mydb
Pool size:: 10
Timeout:: 30 seconds

Output YAML file (config.yaml):

---
document:
  title: Web Application Configuration
  author: DevOps Team

application:
  name: my-web-app
  version: "2.1.0"
  environment: production

server:
  host: "0.0.0.0"
  port: 8080
  workers: 4

database:
  connection_string: "postgresql://localhost:5432/mydb"
  pool_size: 10
  timeout: 30

Example 2: Kubernetes Deployment Documentation

Input ADOC file (deployment.adoc):

= Kubernetes Deployment Spec

== Container Settings

Image:: nginx:1.21
Container port:: 80
Replicas:: 3

== Resource Limits

.CPU
* Request: 100m
* Limit: 200m

.Memory
* Request: 128Mi
* Limit: 256Mi

== Environment Variables

LOG_LEVEL:: info
DEBUG_MODE:: false
API_ENDPOINT:: https://api.example.com

Output YAML file (deployment.yaml):

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: nginx
          image: nginx:1.21
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "200m"
              memory: "256Mi"
          env:
            - name: LOG_LEVEL
              value: "info"
            - name: DEBUG_MODE
              value: "false"
            - name: API_ENDPOINT
              value: "https://api.example.com"

Example 3: CI/CD Pipeline Documentation

Input ADOC file (pipeline.adoc):

= CI/CD Pipeline Configuration

== Pipeline Stages

. Build
. Test
. Deploy

== Build Stage

Build command:: npm run build
Node version:: 18
Cache directories::
* node_modules
* .npm

== Test Stage

Test command:: npm test
Coverage threshold:: 80%

== Deploy Stage

Target environment:: production
Deploy method:: docker
Registry:: ghcr.io/myorg/myapp

Output YAML file (pipeline.yaml):

---
pipeline:
  stages:
    - build
    - test
    - deploy

build:
  stage: build
  command: npm run build
  node_version: "18"
  cache:
    paths:
      - node_modules
      - .npm

test:
  stage: test
  command: npm test
  coverage:
    threshold: 80

deploy:
  stage: deploy
  environment: production
  method: docker
  registry: ghcr.io/myorg/myapp

Frequently Asked Questions (FAQ)

Q: How does the converter handle AsciiDoc document structure in YAML?

A: The converter transforms AsciiDoc's hierarchical structure (sections, subsections) into nested YAML mappings. Headings become keys, and content is organized under appropriate parent keys. Definition lists are converted to key-value pairs, and bullet lists become YAML sequences.

Q: Is the YAML output compatible with Kubernetes and Docker?

A: The YAML output is well-formed and follows YAML 1.2 specification. While the structure reflects the original document content, you may need to adjust the output to match specific Kubernetes or Docker Compose schema requirements depending on your use case.

Q: How are AsciiDoc tables converted to YAML?

A: Tables are converted to YAML sequences of mappings, where each row becomes a mapping with column headers as keys. This structure is ideal for data that will be processed programmatically. Header rows are used to generate the keys for each data row.

Q: What happens to code blocks during conversion?

A: Code blocks are preserved as multi-line YAML strings using literal block scalar notation (|). The language identifier from the AsciiDoc source block can be preserved as a metadata field. This maintains code formatting and indentation in the YAML output.

Q: Can I convert AsciiDoc attributes to YAML metadata?

A: Yes, AsciiDoc document attributes (defined with :attribute: value syntax) are converted to a dedicated metadata section in the YAML output. This preserves author information, version numbers, dates, and custom attributes you've defined in your document.

Q: How does the converter handle special characters?

A: Special characters are properly escaped or quoted according to YAML specifications. Strings containing colons, special characters, or leading/trailing whitespace are automatically quoted. The converter ensures the output is valid, parseable YAML.

Q: Can I use the YAML output directly in CI/CD pipelines?

A: The YAML output provides a structured representation of your document content. For direct use in CI/CD pipelines (GitHub Actions, GitLab CI, etc.), you may need to restructure the output to match the specific syntax required by your platform. The conversion provides a solid starting point.

Q: Is indentation preserved correctly in the YAML output?

A: Yes, the converter generates properly indented YAML using 2-space indentation, which is the most common convention. The hierarchical structure of your AsciiDoc document is accurately reflected through YAML's indentation-based nesting, ensuring valid and readable output.