Convert DOCBOOK to YML

Why Convert DocBook to YML?

Converting DocBook to YML transforms structured technical documentation into the widely-used YAML data format with the .yml extension, which is the convention for Docker Compose, GitLab CI, and many DevOps tools. This conversion extracts configuration data, metadata, and structured settings from documentation and represents them in YAML's clean, indentation-based syntax.

The .yml extension is functionally identical to .yaml but is preferred in certain ecosystems. Docker Compose defaults to docker-compose.yml, GitLab CI uses .gitlab-ci.yml, and many Rails applications use config/*.yml. By converting to .yml specifically, the output files follow the naming conventions expected by these tools and can be used directly in their workflows.

The conversion process maps DocBook's hierarchical XML structure to YAML's indentation-based hierarchy. Sections become nested mappings, tables become key-value pairs, lists become YAML sequences, and descriptive text becomes comments. The converter handles data type inference, proper quoting, and indentation to produce valid, well-formatted YAML that passes linting tools like yamllint.

This conversion is particularly valuable for DevOps teams that document their infrastructure configurations in DocBook and need to generate actual .yml configuration files for deployment. By generating configuration from documentation, teams ensure that deployed services match their documented specifications and reduce the risk of configuration drift.

Key Benefits of Converting DocBook to YML:

• Docker Compose Ready: Generate docker-compose.yml from service documentation
• CI/CD Pipelines: Create GitLab CI, GitHub Actions, and other pipeline configs
• Human-Readable: YML is the most readable data serialization format
• DevOps Convention: .yml is the standard extension in DevOps tooling
• Comment Support: DocBook descriptions become informative YML comments
• Type Safety: Proper quoting prevents YAML implicit type issues
• Documentation Sync: Keep configurations aligned with documentation

Practical Examples

Example 1: Docker Compose Configuration

Input DocBook file (docker-docs.xml):

<article xmlns="http://docbook.org/ns/docbook">
  <title>Docker Services</title>
  <section>
    <title>Web Application</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>image</entry><entry>app:2.1</entry></row>
      <row><entry>restart</entry><entry>always</entry></row>
    </tbody></tgroup></informaltable>
    <para>Ports:</para>
    <itemizedlist>
      <listitem><para>8080:80</para></listitem>
    </itemizedlist>
    <para>Environment:</para>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>NODE_ENV</entry><entry>production</entry></row>
      <row><entry>DB_HOST</entry><entry>postgres</entry></row>
    </tbody></tgroup></informaltable>
  </section>
</article>

Output YML file (docker-compose.yml):

# Docker Services

services:
  web_application:
    image: "app:2.1"
    restart: always
    ports:
      - "8080:80"
    environment:
      NODE_ENV: "production"
      DB_HOST: "postgres"

Example 2: CI/CD Pipeline Definition

Input DocBook file (ci-pipeline.dbk):

<section xmlns="http://docbook.org/ns/docbook">
  <title>CI Pipeline Stages</title>
  <orderedlist>
    <listitem><para>lint</para></listitem>
    <listitem><para>test</para></listitem>
    <listitem><para>build</para></listitem>
    <listitem><para>deploy</para></listitem>
  </orderedlist>
  <section>
    <title>Test Job</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>stage</entry><entry>test</entry></row>
      <row><entry>image</entry><entry>python:3.11</entry></row>
    </tbody></tgroup></informaltable>
  </section>
</section>

Output YML file (.gitlab-ci.yml):

# CI Pipeline Stages

stages:
  - lint
  - test
  - build
  - deploy

test_job:
  stage: test
  image: "python:3.11"

Example 3: Kubernetes Deployment Spec

Input DocBook file (k8s-spec.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Deployment Specification</title>
  <informaltable><tgroup cols="2"><tbody>
    <row><entry>kind</entry><entry>Deployment</entry></row>
    <row><entry>apiVersion</entry><entry>apps/v1</entry></row>
    <row><entry>replicas</entry><entry>3</entry></row>
  </tbody></tgroup></informaltable>
  <section>
    <title>Container</title>
    <informaltable><tgroup cols="2"><tbody>
      <row><entry>name</entry><entry>web-app</entry></row>
      <row><entry>image</entry><entry>myapp:latest</entry></row>
      <row><entry>port</entry><entry>8080</entry></row>
    </tbody></tgroup></informaltable>
  </section>
</section>

Output YML file (deployment.yml):

# Deployment Specification

kind: Deployment
apiVersion: "apps/v1"
replicas: 3

container:
  name: "web-app"
  image: "myapp:latest"
  port: 8080

Frequently Asked Questions (FAQ)

Q: What is the difference between YML and YAML?

A: YML (.yml) and YAML (.yaml) are the same format -- they use identical syntax, parsing rules, and data types. The only difference is the file extension. The YAML specification officially recommends .yaml, but .yml is widely used, especially in Docker Compose (docker-compose.yml), GitLab CI (.gitlab-ci.yml), and Ruby on Rails (database.yml). Our converter produces identical content for both extensions.

Q: How does DocBook structure map to YML?

A: DocBook sections become YML nested mappings (indented key hierarchies). Key-value tables become YML key-value pairs. Lists become YML sequences (- item). Section titles become top-level keys or comments. Descriptive paragraphs become comments (# comment). The converter preserves the hierarchical structure using YAML's indentation-based nesting.

Q: Can I use the output as a docker-compose.yml?

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

Q: How are data types handled in the YML output?

A: The converter carefully handles YAML's implicit typing. Pure integers become unquoted numbers. Strings that YAML might misinterpret (like "yes", "no", "on", "off", version numbers like "3.10") are properly quoted to prevent unexpected type conversion. Boolean values are output as true/false. This prevents the common YAML "Norway problem" and version number truncation issues.

Q: Is the output valid YAML?

A: Yes, the output is valid YAML 1.2 that passes standard linting tools like yamllint. Indentation uses consistent spaces (2 spaces by default), keys are properly formatted, strings are quoted when necessary, and the overall structure is well-formed. The output can be parsed by any YAML library in Python, JavaScript, Go, Ruby, or Java.

Q: How does the converter handle DocBook lists?

A: DocBook itemized lists and ordered lists are converted to YAML sequences. Simple text lists become arrays of strings. Nested lists become nested YAML sequences with proper indentation. Definition lists (<variablelist>) become YAML mappings where the term is the key and the definition is the value.

Q: What happens to DocBook narrative content in YML?

A: Narrative paragraphs, admonitions, and descriptive content that do not represent data are converted to YAML comments (# prefix). Section titles that serve as context become comment headers. Multi-line descriptions use YAML's block scalar syntax (| for literal, > for folded) when stored as values, or multi-line comments when they serve as documentation only.

Q: Can I convert YML back to DocBook?

A: Yes, our converter supports YML to DocBook conversion. The reverse process parses YAML mappings into DocBook sections, key-value pairs into table rows, sequences into lists, and comments into paragraphs. This enables round-trip workflows where DevOps configurations and their DocBook documentation remain synchronized throughout the development lifecycle.