SDMX Technical Documentation

This repository contains the source files for the SDMX Technical Documentation. The documentation is built using MkDocs, a static site generator designed for project documentation.

Getting Started

Prerequisites

• Git (with submodule support)
• Python ≥ 3.12

Clone the Repository

git clone --recurse-submodules <link-to-repository>

The --recurse-submodules flag is required because the components/ directories are Git submodules containing the format-specific documentation.

Install uv

Follow the official installation instructions.

uv manages a virtual environment automatically — no manual activation is needed.

Install Dependencies

uv sync

This installs all locked dependencies (from uv.lock) into a managed virtual environment.

Serve the Documentation

uv run mkdocs serve

This starts a local development server. View the documentation in your browser at http://127.0.0.1:8000.

Submodule Workflow

The components/ directory contains Git submodules, one per SDMX specification. The submodule configuration — including the upstream repository URL and the tracked branch for each component — is maintained in .gitmodules.

Documentation content inside components/ can be edited directly in this working tree — changes are staged and committed inside the submodule, pushed to the upstream submodule branch, and then the parent repository's submodule pointer is updated separately.

Operation	Command
Fetch all submodules after cloning	git submodule update --init --recursive
Sync local submodule config with .gitmodules	git submodule sync --recursive
Update submodules to latest upstream	git submodule update --init --recursive --remote
Commit submodule edits	Two-step: commit and push inside the submodule directory, then stage and commit the updated pointer in the parent repo

Run the sync command after pulling changes that modify .gitmodules (for example, updated submodule URLs or tracked branches), before running git submodule update --init --recursive --remote.

Important: changes pushed to a submodule repository do not automatically trigger a site rebuild. The parent repository stores a pointer to a specific commit in each submodule. To publish updated submodule content, the updated pointer must be committed explicitly in a version branch (e.g., master or X.Y.x) so that the build pipeline picks it up.

Never push directly to gh-pages or gh-pages-preview — these branches are managed by CI.

Repository Structure

This repository is organized into two main areas:

• docs/: Contains the main documentation content for the SDMX Technical Documentation site. This folder includes overarching topics like the general index page.

• components/: Contains individual submodules for each SDMX format and specification. Each component (e.g., sdmx_csv, sdmx_json, sdmx_ml, rest_api, guidelines, information_model) has its own docs/ folder and mkdocs.yml configuration, allowing them to be developed and built independently or integrated into the main site.

When building the full documentation site, MkDocs merges content from both the main docs/ folder and the component submodules to create a unified documentation structure. For the resulting folder structure see the section below, e.g., to create links within the files.

Tooling & Recommended Configuration

Prettier (Markdown Formatter)

This project formats Markdown and YAML files with Prettier. The settings are:

• proseWrap: "always", printWidth: 80, tabWidth: 4 for Markdown
• tabWidth: 2 for YAML files

To use these settings locally, create a .prettierrc file at the repository root with the following content:

{
    "proseWrap": "always",
    "printWidth": 80,
    "tabWidth": 4,
    "overrides": [
        {
            "files": ["*.yml", "*.yaml"],
            "options": { "tabWidth": 2 }
        }
    ]
}

Install the Prettier - Code formatter VS Code extension (esbenp.prettier-vscode) and enable Format on Save to apply formatting automatically.

Recommended VS Code Extensions

Extension	Marketplace ID
Prettier — Code formatter	esbenp.prettier-vscode
Code Spell Checker	streetsidesoftware.code-spell-checker
YAML	redhat.vscode-yaml
markdownlint	DavidAnson.vscode-markdownlint

CI/CD Pipeline

Production Deployment (publish_prod.yml)

• Workflow file: .github/workflows/publish_prod.yml (docs-publish).
• Triggers: push and pull request on main, dev, and docs_v*.*.
• Push result: site deployed to the gh-pages branch using mike deploy --push.
• Pull request result: build and deploy steps run for validation, but no deployment branch is pushed.
• Version label: read from the VERSION file. The format is <version>[|<alias>] — for example, 3.0|latest. The version is required; the alias is optional. When cutting a release, update VERSION to set the deployed version label and alias.
• Note: contributors never deploy manually; CI handles all deployments.

LLM Discovery Files (llms*.txt)

• Source files live at repository root:
  • llms_top.txt
  • llms_version.txt
• Publish behavior:
  • llms_version.txt is published to /<version>/llms.txt on push deployments.
  • llms_top.txt is published to /llms.txt only for pushes to main.
  • Non-main branches MUST NOT modify root /llms.txt.
• Ownership/update process:
  • Update these files through normal pull requests.
  • Keep root content stable and current for primary discovery.
  • Keep version file content valid for every deployed version path.

Contributing

Contributions are welcome — please submit pull requests or open issues.

When contributing, follow these conventions:

• Commit style: Conventional Commits — use prefixes feat, fix, docs, chore, ci, or refactor followed by an imperative description (e.g., fix(ml): correct broken cross-link).
• Branch naming: feature/kebab-case-description for new content branches, X.Y.x for release branches.

A CONTRIBUTING.md with full contribution guidelines is planned for a future update.

License

A formal LICENSE file is planned. Until it is added, please contact the maintainers for licensing information before reusing any content.

Plugins

The following plugins are used:

• mike (https://github.com/jimporter/mike)
• monorepo (https://github.com/backstage/mkdocs-monorepo-plugin)
• to-pdf (https://github.com/orzih/mkdocs-with-pdf)
• search (built-in MkDocs plugin)
• exclude (https://github.com/apenwarr/mkdocs-exclude)

Folder Structure during build

The directory tree below shows the virtual file system MkDocs assembles during a build. Use it as a reference when writing relative links between pages, since the paths here correspond to the URL structure of the built site.

├── assets
│   ├── anchors.js
│   └── style.css
├── framework
│   ├── framework
│   ├── information_model
│   ├── logical_interfaces
│   └── technical_notes
├── getting_started
├── index.md
├── information_model
│   ├── framework
│   ├── information_model
│   ├── logical_interfaces
│   └── technical_notes
├── logical_interfaces
│   ├── framework
│   ├── information_model
│   ├── logical_interfaces
│   └── technical_notes
├── media
│   └── logos
├── csv
│   ├── data_message_field_guide.md
│   ├── index.md
│   └── metadata_message_field_guide.md
├── json
│   ├── data_message
│   ├── index.md
│   ├── metadata_message
│   └── structure_message
├── ml
│   ├── common.md
│   ├── data.md
│   ├── index.md
│   ├── message.md
│   ├── registry.md
│   ├── samples
│   ├── samples.md
│   ├── schemas
│   └── structure.md
├── registry_specification
│   ├── registry_specification
│   └── rest_api
├── rest_api
│   ├── registry_specification
│   └── rest_api
└── technical_notes
    ├── framework
    ├── information_model
    ├── logical_interfaces
    └── technical_notes