Convert AsciiDoc to YAML

Why Convert AsciiDoc to YAML?

Converting AsciiDoc to YAML extracts structured data from documentation and transforms it into the format that dominates modern DevOps and infrastructure management. YAML is the configuration language of choice for Kubernetes, Ansible, Docker Compose, GitHub Actions, and virtually every CI/CD platform. When your AsciiDoc documents contain configuration specifications, deployment parameters, or infrastructure descriptions, converting to YAML creates immediately usable configuration files.

YAML (YAML Ain't Markup Language) was created in 2001 as a human-friendly data serialization format. Its indentation-based structure eliminates the need for brackets and braces, making it exceptionally readable. YAML supports rich data types including strings, integers, floats, booleans, null values, dates, and nested structures (mappings and sequences). It also provides features like anchors and aliases for referencing repeated data, and multi-document support with the --- separator.

The conversion process analyzes AsciiDoc document structure to produce logical YAML output. Section headings become top-level keys, nested sections become indented sub-keys, lists become YAML sequences, and key-value pairs from tables and definition lists become YAML mappings. Document attributes (:key: value) translate directly to YAML key-value pairs. The converter respects YAML's type system, outputting numeric values without quotes and boolean values as true/false.

This conversion is invaluable for platform engineering teams who document their infrastructure in AsciiDoc but deploy using YAML-based tools. Rather than manually transcribing configurations from documentation, the converter produces YAML files that can feed directly into Kubernetes deployments, Ansible playbooks, or Terraform variable files. This approach reduces transcription errors and ensures documentation stays synchronized with actual configuration.

Key Benefits of Converting AsciiDoc to YAML:

• DevOps Ready: Output directly usable in Kubernetes, Ansible, and Docker Compose
• Human Readable: YAML's clean syntax is easy to review and modify
• Configuration Generation: Create config files from documented specifications
• CI/CD Integration: Generate pipeline definitions from documentation
• Comment Support: YAML preserves descriptive context as comments
• Data Type Awareness: Numbers, booleans, and strings properly typed
• Doc-as-Code: Bridge documentation and infrastructure-as-code practices

Practical Examples

Example 1: Kubernetes Deployment Spec

Input AsciiDoc file (deployment-spec.adoc):

= Web Application Deployment

== Container Configuration

* Image: myapp:v2.1.0
* Port: 8080
* Replicas: 3

== Resource Limits

.Resource Allocation
|===
|Resource |Request |Limit

|CPU |250m |500m
|Memory |256Mi |512Mi
|===

== Environment Variables

* DATABASE_URL: postgres://db:5432/myapp
* REDIS_URL: redis://cache:6379
* LOG_LEVEL: info

Output YAML file (deployment-spec.yaml):

container:
  image: "myapp:v2.1.0"
  port: 8080
  replicas: 3

resources:
  requests:
    cpu: "250m"
    memory: "256Mi"
  limits:
    cpu: "500m"
    memory: "512Mi"

environment:
  DATABASE_URL: "postgres://db:5432/myapp"
  REDIS_URL: "redis://cache:6379"
  LOG_LEVEL: info

Example 2: CI/CD Pipeline Documentation

Input AsciiDoc file (pipeline.adoc):

== Build Pipeline

=== Stages

. Lint code
. Run unit tests
. Build Docker image
. Push to registry
. Deploy to staging

=== Triggers

* Push to main branch
* Pull request creation
* Manual dispatch

Output YAML file (pipeline.yaml):

pipeline:
  stages:
    - "Lint code"
    - "Run unit tests"
    - "Build Docker image"
    - "Push to registry"
    - "Deploy to staging"

  triggers:
    - "Push to main branch"
    - "Pull request creation"
    - "Manual dispatch"

Example 3: Application Settings Document

Input AsciiDoc file (settings.adoc):

= Application Configuration

== General Settings

* App Name: MyService
* Debug Mode: false
* Max Connections: 100
* Timeout: 30

== Logging

* Level: warning
* Format: json
* Output: stdout

== Features

* Enable Cache: true
* Enable Metrics: true
* Enable Tracing: false

Output YAML file (settings.yaml):

general:
  app_name: MyService
  debug_mode: false
  max_connections: 100
  timeout: 30

logging:
  level: warning
  format: json
  output: stdout

features:
  enable_cache: true
  enable_metrics: true
  enable_tracing: false

Frequently Asked Questions (FAQ)

Q: What is YAML format?

A: YAML (YAML Ain't Markup Language) is a human-friendly data serialization language. It uses indentation to represent hierarchy, colons for key-value pairs, and dashes for list items. YAML is widely used for configuration files in DevOps tools like Kubernetes, Ansible, Docker Compose, and GitHub Actions. It supports strings, numbers, booleans, null values, dates, nested structures, and multi-line text.

Q: How does AsciiDoc content translate to YAML?

A: AsciiDoc sections become YAML top-level keys. Nested sections become indented sub-keys. Lists translate to YAML sequences (- items). Tables and definition lists become YAML mappings (key: value pairs). Document attributes map directly to YAML key-value pairs. The converter preserves the logical hierarchy of the AsciiDoc document in YAML's indentation-based structure.

Q: Is the YAML output compatible with Kubernetes?

A: The YAML output is syntactically valid YAML that can be used as a starting point for Kubernetes manifests. However, Kubernetes has specific schema requirements (apiVersion, kind, metadata, spec) that depend on the resource type. The converted YAML captures your configuration data which you can then structure into proper Kubernetes manifests by adding the required fields.

Q: What is the difference between YAML and JSON?

A: YAML is a superset of JSON, meaning any valid JSON is also valid YAML. YAML adds human-friendly features: indentation-based structure (no braces), comments, multi-line strings, anchors/aliases for data reuse, and multiple documents in one file. JSON is more compact and faster to parse, while YAML is more readable for configuration files. Both serialize to the same data structures.

Q: Are YAML data types properly handled?

A: Yes, the converter detects data types from AsciiDoc content. Numeric values (42, 3.14) are output as YAML numbers without quotes. Boolean values (true, false) are output as YAML booleans. Strings that could be misinterpreted (like "yes", "no", or version numbers like "3.10") are quoted to prevent YAML's implicit type coercion from causing issues.

Q: Can I use the YAML output with Ansible?

A: The YAML output can serve as variable files, inventory definitions, or configuration data for Ansible. For playbook generation, you would need to add Ansible-specific keys like hosts, tasks, and module names. The converted data is ideal for Ansible vars files that define configuration parameters documented in your AsciiDoc files.

Q: How does indentation work in the YAML output?

A: The YAML output uses 2-space indentation, which is the most common convention in the DevOps community. Each level of nesting (corresponding to AsciiDoc section depth) adds two spaces of indentation. This is consistent with Kubernetes, Ansible, and Docker Compose conventions. The indentation is always spaces, never tabs, as YAML does not allow tab characters for indentation.

Q: What happens to AsciiDoc formatting in YAML?

A: YAML is a data format, not a document format, so text formatting (bold, italic, code) from AsciiDoc is stripped. Only the text content is preserved as YAML string values. If you need to preserve formatted text, the content is stored as plain strings. For multi-line text blocks, YAML's literal (|) or folded (>) block styles are used to maintain readability.