Convert ORG to YAML

Why Convert ORG to YAML?

Converting Org-mode documents to YAML format is essential when you need to generate configuration files or structured data for DevOps tools, CI/CD pipelines, or application settings. While Org-mode excels at personal organization, YAML is the lingua franca of modern infrastructure automation.

YAML is the standard configuration format for Kubernetes, Docker Compose, Ansible, GitHub Actions, and countless other DevOps tools. Converting your Org-mode structured data to YAML enables direct integration with these platforms and tools.

The conversion is particularly valuable for developers who plan infrastructure or document configurations in Org-mode. Your hierarchical notes and property drawers translate naturally to YAML's nested structure, producing ready-to-use configuration files.

YAML's human-readable format makes it ideal for version-controlled configuration. Converting from Org-mode preserves your data structure while producing files that are easy for teammates to review and modify, even without Org-mode knowledge.

Key Benefits of Converting ORG to YAML:

• DevOps Ready: Use with Kubernetes, Docker, Ansible
• CI/CD Integration: GitHub Actions, GitLab CI workflows
• Human Readable: Clear, minimal syntax
• Version Control: Clean diffs in git
• Language Support: Parsers in every language
• Hierarchical Data: Natural structure mapping
• API Specs: OpenAPI/Swagger definitions

Practical Examples

Example 1: Application Configuration

Input ORG file (config.org):

#+TITLE: Application Config

* Application
:PROPERTIES:
:name: myapp
:version: 1.0.0
:environment: production
:END:

** Server
- host: 0.0.0.0
- port: 8080
- workers: 4

** Database
- driver: postgresql
- host: db.example.com
- port: 5432
- name: myapp_prod
- pool_size: 10

** Logging
- level: info
- format: json
- output: stdout

Output YAML file (config.yaml):

application:
  name: myapp
  version: 1.0.0
  environment: production

  server:
    host: 0.0.0.0
    port: 8080
    workers: 4

  database:
    driver: postgresql
    host: db.example.com
    port: 5432
    name: myapp_prod
    pool_size: 10

  logging:
    level: info
    format: json
    output: stdout

Example 2: Docker Compose Style

Input ORG file (services.org):

* Services

** web
- image: nginx:alpine
- ports: 80:80, 443:443
- depends_on: api, db

** api
- build: ./api
- environment:
  - DATABASE_URL=postgres://db/app
  - REDIS_URL=redis://cache
- ports: 8080:8080

** db
- image: postgres:15
- volumes: pgdata:/var/lib/postgresql/data
- environment:
  - POSTGRES_DB=app
  - POSTGRES_USER=admin

Output YAML file (services.yaml):

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - api
      - db

  api:
    build: ./api
    environment:
      - DATABASE_URL=postgres://db/app
      - REDIS_URL=redis://cache
    ports:
      - "8080:8080"

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=app
      - POSTGRES_USER=admin

Example 3: CI/CD Pipeline

Input ORG file (pipeline.org):

* CI Pipeline

** Triggers
- push to main
- pull_request

** Jobs

*** test
- runs-on: ubuntu-latest
- steps:
  1. Checkout code
  2. Setup Python 3.11
  3. Install dependencies
  4. Run pytest

*** build
- runs-on: ubuntu-latest
- needs: test
- steps:
  1. Checkout code
  2. Build Docker image
  3. Push to registry

Output YAML file (pipeline.yaml):

name: CI Pipeline

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Python 3.11
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run pytest
        run: pytest

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Build Docker image
        run: docker build -t myapp .
      - name: Push to registry
        run: docker push myapp

Frequently Asked Questions (FAQ)

Q: What is YAML?

A: YAML (YAML Ain't Markup Language) is a human-readable data serialization format created in 2001. It's designed to be easy to read and write, using indentation to represent hierarchy. YAML is the standard configuration format for DevOps tools like Kubernetes, Docker Compose, Ansible, and GitHub Actions.

Q: How is Org structure converted to YAML?

A: Org-mode headings become YAML keys, and nested headings become nested mappings. Property drawers become key-value pairs. Lists become YAML sequences. The hierarchical structure maps naturally between the two formats.

Q: What about Org-mode properties?

A: Property drawers (:PROPERTIES: ... :END:) are ideal for YAML conversion. Each property becomes a key-value pair in the YAML output. This makes Org-mode an excellent way to draft configuration data before export.

Q: Can I use the output with Kubernetes?

A: The basic YAML output needs to follow Kubernetes' schema for deployment manifests, services, etc. While the converter produces valid YAML, you may need to adjust the structure to match specific Kubernetes resource types.

Q: How are data types handled?

A: The converter attempts to infer types: numbers remain numbers, true/false become booleans, and other values become strings. YAML's flexible typing means most conversions produce correct results without manual intervention.

Q: What about multi-line strings?

A: Org-mode paragraphs and multi-line content are converted to YAML's literal block scalar (|) or folded block scalar (>) syntax. This preserves formatting for descriptions, scripts, and other long text content.

Q: Can I convert YAML back to Org-mode?

A: Yes, YAML data can be converted back to Org-mode. YAML mappings become headings with properties, and sequences become lists. This is useful for importing existing configurations into your Org-mode workflow.

Q: Is the output valid YAML 1.2?

A: Yes, the converter produces YAML 1.2 compliant output that can be parsed by modern YAML libraries. The output uses safe, widely-compatible constructs that work across different YAML parsers.