Convert DOCBOOK to YAML

Why Convert DocBook to YAML?

Converting DocBook to YAML extracts structured data and configuration information from technical documentation into a format that is both human-readable and machine-parseable. YAML's clean, indentation-based syntax is ideal for configuration files, data serialization, and infrastructure-as-code workflows where readability is paramount.

YAML (YAML Ain't Markup Language) has become the dominant configuration format in DevOps and cloud-native computing. Docker Compose, Kubernetes, Ansible, GitHub Actions, GitLab CI, and countless other tools use YAML for their configuration. By converting DocBook documentation to YAML, you can generate configuration files directly from documented specifications.

The conversion process maps DocBook's hierarchical sections to YAML nested mappings. Key-value tables become YAML key-value pairs. Lists become YAML sequences. Descriptive text becomes YAML comments. The converter automatically infers data types, converting numeric values to integers or floats, boolean-like values to true/false, and preserving strings with proper quoting.

This conversion is particularly valuable for teams that document their infrastructure configurations in DocBook and want to generate actual YAML configuration files. It supports the documentation-as-code paradigm where the authoritative documentation and the deployed configuration stay synchronized, reducing configuration drift and deployment errors.

Key Benefits of Converting DocBook to YAML:

• Configuration Generation: Create config files from documented specifications
• Human-Readable: YAML is the most readable data serialization format
• DevOps Ready: Output works with Docker, Kubernetes, Ansible, CI/CD
• Deep Nesting: YAML handles deeply nested structures elegantly
• Comment Preservation: DocBook descriptions become YAML comments
• Type Inference: Automatic detection of strings, numbers, and booleans
• Multi-Document: Multiple DocBook sections can become separate YAML documents

Practical Examples

Example 1: Application Configuration

Input DocBook file (app-config.xml):

<article xmlns="http://docbook.org/ns/docbook">
  <title>Application Settings</title>
  <section>
    <title>Database</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>host</entry><entry>db.example.com</entry></row>
      <row><entry>port</entry><entry>5432</entry></row>
      <row><entry>name</entry><entry>production_db</entry></row>
      <row><entry>ssl</entry><entry>true</entry></row>
    </tbody></tgroup></informaltable>
  </section>
  <section>
    <title>Logging</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>level</entry><entry>info</entry></row>
      <row><entry>format</entry><entry>json</entry></row>
    </tbody></tgroup></informaltable>
  </section>
</article>

Output YAML file (app-config.yaml):

# Application Settings

database:
  host: "db.example.com"
  port: 5432
  name: "production_db"
  ssl: true

logging:
  level: "info"
  format: "json"

Example 2: Service List Documentation

Input DocBook file (services.dbk):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Microservices</title>
  <section>
    <title>API Gateway</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>image</entry><entry>gateway:latest</entry></row>
      <row><entry>port</entry><entry>80</entry></row>
    </tbody></tgroup></informaltable>
    <para>Dependencies:</para>
    <itemizedlist>
      <listitem><para>auth-service</para></listitem>
      <listitem><para>user-service</para></listitem>
    </itemizedlist>
  </section>
</section>

Output YAML file (services.yaml):

# Microservices

api_gateway:
  image: "gateway:latest"
  port: 80
  depends_on:
    - auth-service
    - user-service

Example 3: CI/CD Pipeline Documentation

Input DocBook file (pipeline.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Build Pipeline</title>
  <orderedlist>
    <listitem><para>checkout code</para></listitem>
    <listitem><para>install dependencies</para></listitem>
    <listitem><para>run tests</para></listitem>
    <listitem><para>build artifacts</para></listitem>
    <listitem><para>deploy to staging</para></listitem>
  </orderedlist>
</section>

Output YAML file (pipeline.yaml):

# Build Pipeline

steps:
  - checkout code
  - install dependencies
  - run tests
  - build artifacts
  - deploy to staging

Frequently Asked Questions (FAQ)

Q: What is YAML format?

A: YAML (YAML Ain't Markup Language) is a human-friendly data serialization format created in 2001. It uses indentation to represent hierarchy, dashes for lists, and colons for key-value pairs. YAML is the standard format for Docker Compose, Kubernetes manifests, Ansible playbooks, GitHub Actions, and many other DevOps tools.

Q: How does DocBook structure map to YAML?

A: DocBook sections map to YAML nested mappings (key hierarchies). Key-value tables become YAML key-value pairs at the appropriate nesting level. Lists become YAML sequences (- item). Section titles become YAML keys or comments. Descriptive paragraphs become YAML comments (# comment). The converter preserves the logical hierarchy of the DocBook source.

Q: How are data types handled?

A: The converter infers YAML data types from content. Pure integers become unquoted numbers (port: 8080). Floating-point values preserve their precision. "true" and "false" become YAML booleans. Strings that could be misinterpreted (like "no", version numbers, or hex values) are quoted to prevent YAML's implicit type conversion from causing issues.

Q: What is the difference between YAML and YML?

A: YAML (.yaml) and YML (.yml) are the same format with different file extensions. The YAML specification officially recommends .yaml, but .yml is widely used (especially on Windows systems with historical 3-character extension limits). Docker Compose uses .yml by convention, while Ansible and GitHub Actions use .yaml. Our converter produces identical output for both.

Q: Can I use the output with Docker Compose?

A: If your DocBook document describes Docker service configurations with appropriate structure (services, networks, volumes), the output can serve as a starting point for a docker-compose.yml file. The YAML structure will need to follow Docker Compose's expected schema. The converter preserves section hierarchies and key-value pairs that map naturally to Docker Compose syntax.

Q: How does the converter handle multi-line content?

A: Multi-line content from DocBook paragraphs uses YAML's block scalar syntax. The literal block scalar (|) preserves line breaks exactly, while the folded block scalar (>) joins lines with spaces. The converter chooses the appropriate style based on whether the original content requires exact line break preservation (code blocks use |, descriptions use >).

Q: Are YAML comments preserved from DocBook?

A: Yes, DocBook descriptive content that does not map to data values is converted to YAML comments. Section titles become comment headers, descriptive paragraphs become inline comments, and admonitions (NOTE, WARNING) become commented blocks above relevant configuration sections. This preserves the documentation context alongside the data.

Q: Can I convert YAML back to DocBook?

A: Yes, our converter supports YAML to DocBook conversion. The reverse process maps YAML mappings to DocBook sections, key-value pairs to table rows, sequences to itemized lists, and comments to paragraphs. This round-trip capability enables documentation-as-code workflows where YAML configurations and their DocBook documentation stay synchronized.