Convert MediaWiki to YML

Why Convert MediaWiki to YML?

Converting MediaWiki markup to YML format is the preferred approach when your target systems expect the .yml file extension. While .yml and .yaml are technically identical in format, many widely-used tools and frameworks specifically use the .yml convention: Travis CI expects .travis.yml, GitLab CI uses .gitlab-ci.yml, Ruby on Rails uses database.yml and application.yml, and Spring Boot recognizes application.yml. Converting wiki documentation directly to .yml files ensures seamless integration with these ecosystems.

Organizations commonly maintain detailed configuration documentation, deployment runbooks, and infrastructure specifications on internal MediaWiki instances. When this information needs to be transformed into actual configuration files for CI/CD pipelines, container orchestration, or application settings, converting from MediaWiki to YML eliminates the error-prone process of manually transcribing values from wiki pages into configuration files.

The conversion process extracts the structured content from MediaWiki markup and maps it to YML's clean, indentation-based syntax. Wiki sections become nested YML mappings, bulleted lists become YML sequences, key-value data from wiki tables or definition lists becomes properly typed YML entries, and hierarchical information preserves its nesting depth. The result is clean, well-structured YML that follows best practices for readability and maintainability.

YML output from wiki conversion is particularly useful for generating starter configurations, documenting expected configuration values with inline comments, and creating configuration templates that teams can customize for their specific environments. The human-readable nature of YML makes the converted output immediately understandable and editable, maintaining the documentation quality that was present in the original wiki content.

Key Benefits of Converting MediaWiki to YML:

• CI/CD Integration: Generate .travis.yml, .gitlab-ci.yml, and other pipeline configs from wiki docs
• Rails Convention: Produce .yml files matching Ruby on Rails configuration expectations
• Spring Boot: Create application.yml settings from documented configurations
• Docker Compose: Generate docker-compose.yml from wiki service documentation
• Clean Syntax: YML produces readable, well-structured configuration output
• Comment Preservation: Wiki notes and descriptions become YML comments for context
• Automation Ready: Output files can be immediately used by configuration management tools

Practical Examples

Example 1: CI/CD Pipeline Documentation to Config

Input MediaWiki file (pipeline.mediawiki):

== CI/CD Pipeline ==

=== Build Stage ===
* '''Image:''' python:3.12
* '''Script:'''
** pip install -r requirements.txt
** python -m pytest

=== Deploy Stage ===
* '''Environment:''' production
* '''Script:'''
** Deploy to {{Server|app.example.com}}
** Run database migrations

=== Notifications ===
* '''Email:''' [email protected]
* '''Slack channel:''' #deployments

Output YML file (pipeline.yml):

# CI/CD Pipeline Configuration

build:
  image: "python:3.12"
  script:
    - "pip install -r requirements.txt"
    - "python -m pytest"

deploy:
  environment: "production"
  script:
    - "Deploy to app.example.com"
    - "Run database migrations"

notifications:
  email: "[email protected]"
  slack_channel: "#deployments"

Example 2: Application Settings Documentation

Input MediaWiki file (app_settings.mediawiki):

== Application Settings ==

=== Logging ===
* '''Level:''' INFO
* '''File:''' /var/log/app.log
* '''Max size:''' 100
* '''Rotation:''' daily

=== Security ===
* '''CORS enabled:''' Yes
* '''Allowed origins:'''
** https://example.com
** https://app.example.com
* '''Rate limit:''' 1000 requests per minute

{{Warning|Never commit secrets to the YML file.}}

Output YML file (app_settings.yml):

# Application Settings
# Warning: Never commit secrets to the YML file.

logging:
  level: "INFO"
  file: "/var/log/app.log"
  max_size: 100
  rotation: "daily"

security:
  cors_enabled: true
  allowed_origins:
    - "https://example.com"
    - "https://app.example.com"
  rate_limit: 1000  # requests per minute

Example 3: Service Registry from Wiki

Input MediaWiki file (services.mediawiki):

== Microservices ==

{| class="wikitable"
|-
! Service !! Port !! Health Check !! Replicas
|-
| '''auth-service''' || 8081 || /health || 3
|-
| '''api-gateway''' || 8080 || /status || 2
|-
| '''notification''' || 8082 || /ping || 1
|}

''All services use Docker containers.''

Output YML file (services.yml):

# Microservices
# All services use Docker containers.

services:
  - name: "auth-service"
    port: 8081
    health_check: "/health"
    replicas: 3
  - name: "api-gateway"
    port: 8080
    health_check: "/status"
    replicas: 2
  - name: "notification"
    port: 8082
    health_check: "/ping"
    replicas: 1

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 (three characters) versus .yaml (four characters). Both are fully interchangeable and parsed identically by all YAML libraries. The .yml extension is historically associated with Ruby on Rails and CI/CD tools (Travis CI, GitLab CI), while .yaml is favored by newer tools like Kubernetes and Ansible.

Q: Why choose .yml over .yaml for the output?

A: Choose .yml when your target system expects that specific extension. Travis CI requires .travis.yml, GitLab CI expects .gitlab-ci.yml, Ruby on Rails uses database.yml and config/*.yml, and Spring Boot recognizes application.yml. If your toolchain uses the .yml convention, converting directly to .yml avoids the need to rename files after conversion.

Q: How are MediaWiki sections mapped to YML structure?

A: MediaWiki headings become YML mapping keys (converted to snake_case for compatibility), with subsections nested as child mappings. List items become YML sequences, key-value data from wiki tables becomes nested mappings with proper data types, and plain text content becomes string values. The section hierarchy preserves its depth in YML's indentation structure.

Q: Does the conversion preserve data types?

A: Yes! Numbers are stored as integers or floats, "Yes"/"No" values become booleans (true/false), and text remains as quoted strings. Port numbers, counts, and other numeric values are correctly typed so they can be used directly in configuration contexts without type conversion issues.

Q: Can I use the output with Docker Compose?

A: The converted YML provides structured data extracted from your wiki documentation. While it produces valid YML, Docker Compose expects a specific schema (version, services, volumes, networks). You may need to reorganize the output to match Docker Compose's expected structure. The conversion handles data extraction; schema compliance may require adjustment.

Q: How are wiki notes and warnings preserved?

A: MediaWiki note and warning templates are converted to YML comments (lines starting with #). This preserves important documentation context within the configuration file without affecting the YML data structure. Comments in YML files are an important best practice for configuration documentation.

Q: Is the output valid for YAML linters?

A: Yes! The output follows YAML best practices and passes standard YAML linters like yamllint. Proper indentation (spaces only, no tabs), correct quoting of special characters, and valid data type representation ensure the output is clean, standards-compliant YML that will pass validation checks in CI/CD pipelines.

Q: Can I convert multiple MediaWiki files to YML at once?

A: Yes! Upload multiple MediaWiki files simultaneously and each will be independently converted to its own .yml file. This is perfect for batch-generating configuration files from multiple wiki documentation pages, such as converting separate service documentation pages into individual service configuration files.