Convert ADOC to YML

Drag and drop files here or click to select.
Max file size 100mb.

Uploading progress:

ADOC vs YML Format Comparison

Aspect	ADOC (Source Format)	YML (Target Format)
Format Overview	ADOC AsciiDoc Markup Language A lightweight, semantic markup language designed for writing technical documentation, articles, books, and man pages. AsciiDoc offers richer formatting capabilities than Markdown while remaining human-readable as plain text. Technical Docs Lightweight Markup	YML YAML Ain't Markup Language A human-friendly data serialization standard commonly used for configuration files, CI/CD pipelines, container orchestration, and data exchange between programming languages. YML is a recognized alias for the YAML format. Data Serialization Configuration
Technical Specifications	Structure: Plain text with semantic markup notation Standard: AsciiDoc Language specification Format: Plain text with formatting directives Compression: None (plain text) Extensions: .adoc, .asciidoc, .asc	Structure: Indentation-based key-value data Standard: YAML 1.2 (2009) / JSON superset Format: Plain text with indentation hierarchy Compression: None (plain text) Extensions: .yml, .yaml
Syntax Examples	AsciiDoc uses semantic markup: = Document Title Author Name :toc: left :icons: font == Introduction This is a bold and _italic_ text. === Subsection * Item one * Item two ** Nested item [source,python] ---- print("Hello World") ---- NOTE: This is a note admonition.	YML uses indentation-based structure: title: "Document Title" author: "Author Name" toc: left icons: font sections: - name: "Introduction" content: "This is bold and italic text." subsections: - name: "Subsection" items: - "Item one" - "Item two" nested_items: - "Nested item" code_blocks: - language: python code: 'print("Hello World")' notes: - "This is a note admonition."
Content Support	Headings (multiple levels with = signs) Bold, italic, and monospace formatting Admonitions (NOTE, TIP, WARNING, etc.) Source code blocks with syntax highlighting Tables with complex formatting Cross-references and anchors Include directives for modular docs Conditional content and attributes	Key-value pairs and mappings Sequences (ordered lists) Nested data structures Multi-line strings (literal and folded) Anchors and aliases for reuse Comments with # prefix Multiple data types (strings, numbers, booleans) Multi-document support (--- separator)
Advantages	Richer formatting than Markdown Built-in table of contents generation Conditional content processing Include directives for modular documents Admonition blocks for warnings/notes Excellent for book-length content	Human-readable data format Native support in most programming languages Industry standard for CI/CD configuration Perfect for Docker and Kubernetes configs Superset of JSON (valid JSON is valid YAML) Supports complex nested data structures Widely supported by DevOps tools
Disadvantages	Smaller community than Markdown Steeper learning curve for advanced features Fewer editor plugins available Requires processor (Asciidoctor) to render Less universal recognition outside tech docs	Indentation sensitivity causes errors No rich text formatting support Complex nested structures can be hard to read Tab characters not allowed for indentation Security concerns with arbitrary code execution
Common Uses	Technical documentation and manuals API reference documentation Book authoring (O'Reilly uses AsciiDoc) Man pages and help files Software project documentation	CI/CD pipeline configuration (GitHub Actions, GitLab CI) Docker Compose files Kubernetes manifests and Helm charts Ansible playbooks and roles Application configuration files Cloud infrastructure definitions (CloudFormation)
Best For	Writing comprehensive technical documentation Creating books and long-form content Generating multi-format output (HTML, PDF, EPUB) Documenting complex software projects	DevOps and infrastructure configuration Application settings and environment setup Data exchange between services Container orchestration definitions
Version History	Introduced: 2002 (Stuart Rackham) Processor: Asciidoctor (Ruby, 2013+) Status: Actively developed and maintained Evolution: AsciiDoc.py to Asciidoctor	Introduced: 2001 (Clark Evans, Ingy dot Net, Oren Ben-Kiki) Latest: YAML 1.2 (2009), JSON-compatible Status: Actively used, industry standard Evolution: YAML 1.0 (2004) to YAML 1.2 (2009)
Software Support	Asciidoctor: Primary processor (Ruby, Java, JavaScript) IDEs: IntelliJ, VS Code, Atom plugins Converters: Pandoc, Asciidoctor backends Other: GitHub, GitLab rendering support	Libraries: PyYAML, SnakeYAML, js-yaml, go-yaml Tools: Docker, Kubernetes, Ansible, Terraform IDEs: All major editors with YAML support Other: GitHub Actions, GitLab CI, CircleCI

Why Convert ADOC to YML?

Converting AsciiDoc (ADOC) to YML (YAML) transforms your structured technical documentation into a machine-readable data format that is widely used across the DevOps ecosystem. While AsciiDoc excels at presenting human-readable documentation with rich formatting, YAML provides the structured key-value data representation needed by configuration management tools, CI/CD pipelines, and container orchestration platforms.

Many development teams maintain their project documentation in AsciiDoc format but need to extract structured metadata, configuration parameters, or content hierarchies into YAML for automated processing. For example, an AsciiDoc-based API reference can be converted to YAML to generate OpenAPI specifications, or documentation attributes can be extracted into YAML configuration files for static site generators like Antora or Jekyll.

The conversion process maps AsciiDoc's hierarchical heading structure to nested YAML keys, transforms attribute definitions into key-value pairs, and converts lists into YAML sequences. Code blocks, admonitions, and table data are preserved as structured YAML entries, making the content accessible to scripts, automation tools, and data processing pipelines.

This conversion is particularly valuable in documentation-as-code workflows where AsciiDoc content needs to feed into automated build systems. YAML output can be consumed by CI/CD tools like GitHub Actions or GitLab CI, integrated into Kubernetes ConfigMaps, or used as input for template engines that generate deployment configurations from documentation metadata.

Key Benefits of Converting ADOC to YML:

Machine-Readable Output: Transform human-readable documentation into structured data for automated processing
CI/CD Integration: Use extracted content in GitHub Actions, GitLab CI, and other pipeline configurations
Configuration Generation: Generate Docker Compose, Kubernetes, and Ansible configuration files from documentation
Metadata Extraction: Pull document attributes, parameters, and structured data into YAML key-value pairs
Documentation-as-Code: Bridge the gap between documentation and infrastructure configuration
Cross-Tool Compatibility: YAML is supported by virtually every DevOps and automation tool
Hierarchical Data Mapping: AsciiDoc heading structure maps naturally to nested YAML keys

Practical Examples

Example 1: API Documentation to Configuration

Input ADOC file (api-config.adoc):

= API Service Configuration
:version: 2.5.0
:author: DevOps Team

== Server Settings

* Host: api.example.com
* Port: 8443
* Protocol: HTTPS

== Authentication

=== OAuth2 Settings

* Provider: Auth0
* Client ID: abc123
* Scopes: read, write, admin

== Rate Limiting

|===
| Tier | Requests/min | Burst

| Free
| 60
| 100

| Pro
| 600
| 1000

| Enterprise
| 6000
| 10000
|===

Output YML file (api-config.yml):

title: "API Service Configuration"
version: "2.5.0"
author: "DevOps Team"

server_settings:
  host: "api.example.com"
  port: 8443
  protocol: "HTTPS"

authentication:
  oauth2_settings:
    provider: "Auth0"
    client_id: "abc123"
    scopes:
      - "read"
      - "write"
      - "admin"

rate_limiting:
  - tier: "Free"
    requests_per_min: 60
    burst: 100
  - tier: "Pro"
    requests_per_min: 600
    burst: 1000
  - tier: "Enterprise"
    requests_per_min: 6000
    burst: 10000

Example 2: Deployment Guide to Docker Compose

Input ADOC file (deployment.adoc):

= Deployment Guide
:env: production

== Services

=== Web Application

* Image: myapp/web:latest
* Port mapping: 80:3000
* Environment variables:
** NODE_ENV=production
** DB_HOST=database

=== Database

* Image: postgres:15
* Port mapping: 5432:5432
* Volumes: pgdata:/var/lib/postgresql/data

=== Cache

* Image: redis:7-alpine
* Port mapping: 6379:6379

NOTE: Ensure all volumes are backed up daily.

Output YML file (deployment.yml):

title: "Deployment Guide"
environment: "production"

services:
  web_application:
    image: "myapp/web:latest"
    port_mapping: "80:3000"
    environment:
      - "NODE_ENV=production"
      - "DB_HOST=database"

  database:
    image: "postgres:15"
    port_mapping: "5432:5432"
    volumes:
      - "pgdata:/var/lib/postgresql/data"

  cache:
    image: "redis:7-alpine"
    port_mapping: "6379:6379"

notes:
  - "Ensure all volumes are backed up daily."

Example 3: CI/CD Pipeline Documentation to Workflow

Input ADOC file (pipeline.adoc):

= CI/CD Pipeline Specification
:project: MyProject

== Stages

=== Build

* Runner: ubuntu-latest
* Steps:
** Checkout code
** Install dependencies
** Compile source

=== Test

* Runner: ubuntu-latest
* Steps:
** Run unit tests
** Run integration tests
** Generate coverage report

=== Deploy

* Runner: ubuntu-latest
* Condition: branch is main
* Steps:
** Build Docker image
** Push to registry
** Deploy to Kubernetes

Output YML file (pipeline.yml):

title: "CI/CD Pipeline Specification"
project: "MyProject"

stages:
  build:
    runner: "ubuntu-latest"
    steps:
      - "Checkout code"
      - "Install dependencies"
      - "Compile source"

  test:
    runner: "ubuntu-latest"
    steps:
      - "Run unit tests"
      - "Run integration tests"
      - "Generate coverage report"

  deploy:
    runner: "ubuntu-latest"
    condition: "branch is main"
    steps:
      - "Build Docker image"
      - "Push to registry"
      - "Deploy to Kubernetes"

Frequently Asked Questions (FAQ)

Q: What is the difference between YML and YAML?

A: YML and YAML refer to the same data serialization format. The only difference is the file extension: .yml and .yaml are both valid and widely used. Some tools and communities prefer .yml (e.g., Docker Compose uses docker-compose.yml), while others prefer .yaml (e.g., Kubernetes documentation). The content and syntax are identical regardless of which extension is used.

Q: How are AsciiDoc headings mapped to YAML structure?

A: AsciiDoc headings are converted to nested YAML keys based on their level. A level-1 heading (= Title) becomes a top-level key, a level-2 heading (== Section) becomes a second-level key, and so on. This creates a natural hierarchical mapping where the document's outline structure translates directly into YAML's indentation-based nesting.

Q: Are AsciiDoc attributes preserved in the YAML output?

A: Yes, AsciiDoc document attributes (defined with :attribute: value syntax) are converted to top-level YAML key-value pairs. For example, :version: 2.0 becomes version: "2.0" in the YAML output. This makes it easy to extract metadata like version numbers, authors, and configuration parameters from your documentation.

Q: Can I use the YAML output directly in Docker Compose or Kubernetes?

A: The converted YAML provides a structured representation of your AsciiDoc content, but it may need manual adjustments to match the exact schema required by Docker Compose, Kubernetes, or other specific tools. The output preserves the data hierarchy and values, which can serve as a strong starting point for creating configuration files.

Q: How are AsciiDoc tables converted to YAML?

A: AsciiDoc tables are converted to YAML sequences (lists) of mappings. Each row becomes a list item with column headers as keys. For example, a table with columns "Name" and "Value" becomes a list of objects with name and value properties. This structured representation makes the table data easily accessible for programmatic processing.

Q: What happens to AsciiDoc code blocks during conversion?

A: AsciiDoc source code blocks (delimited by ----) are preserved in the YAML output as multi-line string values. The language attribute from the [source,language] directive is stored as a separate key, allowing downstream tools to identify the programming language. The code content itself is stored using YAML's literal block scalar (|) notation to preserve formatting.

Q: Does the converter handle AsciiDoc include directives?

A: The converter processes the content of the uploaded ADOC file as-is. Include directives (include::file.adoc[]) reference external files that are not available during conversion. For best results, resolve all includes before conversion by using Asciidoctor to produce a single consolidated document, then convert that to YML.

Q: Can I convert back from YML to ADOC?

A: While a reverse conversion is technically possible, it will not fully restore AsciiDoc-specific formatting such as admonitions, cross-references, inline markup styles, and include directives. YAML stores structured data but does not retain rich text presentation. Always keep your original ADOC files if you need the full documentation formatting later.