About This Documentation Infrastructure

The SRDD documentation uses Markdown files stored in a GitHub repository's `documentation` directory. Each Markdown file contains YAML front matter for metadata and uses standard GitHub-flavored Markdown for content. Cross-document linking employs a placeholder syntax to facilitate platform-agnostic links. A GitHub Actions pipeline automatically handles building and publishing the documentation. The pipeline first transforms placeholders for GitHub Pages deployment using Jekyll. Next, it syncs the content to Dev.to via a two-pass process. The first pass creates or updates Dev.to articles, capturing generated URLs. The second pass resolves internal links on Dev.to, using the generated URL map. Canonical URLs on Dev.to articles point to the GitHub Pages version, ensuring SEO benefits and a single source of truth. Adding new documentation involves creating a Markdown file and linking it using the placeholder syntax. The pipeline requires a Dev.to API key and the GitHub Pages URL as environment variables. This approach enables "write once, publish everywhere" functionality for the SRDD documentation. This process ensures the content is consistently available across multiple platforms.