About This Documentation Infrastructure

Source: Dev.to

Overview

This page describes how the SRDD documentation is structured, built, and published. All documentation lives as Markdown files in the ./documentation directory of the GitHub repository and serves as the single source of truth.

Documentation Structure

documentation/
├── index.md              # Entry point / overview
├── pitches.md            # Various length summaries
├── SRDD-part1-of-4.md    # Article series
├── SRDD-part2-of-4.md
├── SRDD-part3-of-4.md
├── SRDD-part4-of-4.md
├── CONTRIBUTING.md       # Contribution guide
├── about.md              # This file
└── .sync-state.json      # Dev.to sync state (auto‑generated)

Each Markdown file uses YAML front matter for metadata (title, description, etc.) and standard GitHub‑flavored Markdown for content.

Placeholder Syntax

Internal links use a placeholder pattern that is transformed depending on the target platform:

See [Part 1](https://dev.to/bbos/srdd-part-1-of-4-the-best-ai-coding-methodology-8fe) for details.

The {{devto:slug}} pattern is replaced as follows:

This allows documents to link to each other without hard‑coding URLs that differ across platforms.

Publishing Workflow

A single GitHub Actions workflow (.github/workflows/deploy-and-sync.yml) handles all publishing steps.

Transform Dev.to Placeholders for GitHub Pages

- name: Transform devto placeholders for GHP
  run: |
    find ./documentation -name "*.md" -exec sed -i -E \
      's/\{\{devto:([^}]+)\}\}/.\/\1.md/g' {} \;

Build with Jekyll

- name: Build with Jekyll
  uses: actions/jekyll-build-pages@v1
  with:
    source: ./documentation
    destination: ./_site

Pipeline Summary

1. Copies assets into the documentation directory.
2. Transforms {{devto:slug}} placeholders to relative .md links.
3. Builds the site with Jekyll.
4. Deploys to GitHub Pages.

After the GitHub Pages deployment completes, a second job syncs the posts to Dev.to.

sync-to-devto:
  needs: deploy  # Run after deploy so canonical URLs are live
  steps:
    - name: Sync posts to Dev.to
      env:
        DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
        SITE_URL: ${{ vars.SITE_URL }}

Sync Script

The sync script (scripts/sync-to-devto/sync-to-devto.js) performs a two‑pass synchronization:

1. Pass 1 – For each Markdown file:

   • Parse front matter and content.
   • Build the canonical URL (pointing to GitHub Pages).
   • Transform content (absolute URLs for images, strip styles).
   • Create or update the Dev.to article via API.
   • Capture the returned Dev.to URL.

2. Pass 2 – Re‑parse documents containing {{devto:slug}} placeholders, replace them with the actual Dev.to URLs obtained in Pass 1, and update the articles again.

URL Map Example (Pass 1)

{
  "index": "https://dev.to/bbos/srdd-is-the-best...-4k2n",
  "SRDD-part1-of-4": "https://dev.to/bbos/why-srdd-exists-2j8m"
  // …
}

This two‑pass approach guarantees that all cross‑references resolve correctly despite Dev.to’s dynamic URL generation.

Hashing and Sync State

To avoid unnecessary API calls, each post’s content is hashed (SHA‑256, truncated to 32 characters). The hashes are stored in documentation/.sync-state.json.

Sync State Example

{
  "index": {
    "hash": "a1b2c3d4e5f67890...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/srdd-...-4k2n"
  },
  "pitches": {
    "hash": "f0e1d2c3b4a59687...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/pitches-...-2j8m"
  }
}

The url field caches each article’s Dev.to URL, enabling placeholder resolution even when API rate limits prevent fetching URLs.

Sync Logic

• On each run, current hashes are compared with stored hashes.
• Only posts with differing hashes are synced.
• The updated state file is committed back to the repository.

Force Full Sync

To sync all posts regardless of changes, set the FORCE_SYNC environment variable:

env:
  FORCE_SYNC: 'true'

Or run locally:

node sync-to-devto.js --force

Refresh URL Cache

If articles were renamed or URLs changed, refresh the cached URLs:

env:
  REFRESH_URLS: 'true'

Or run locally:

node sync-to-devto.js --refresh-urls

Canonical URLs and SEO Benefits

Every article on Dev.to includes a canonical_url pointing to the GitHub Pages version, e.g.:

canonical_url: https://docs-bbos.github.io/srdd/SRDD-part1-of-4/

Benefits:

• SEO consolidation: Search rankings accrue to a single URL.
• Platform flexibility: Content can appear on Dev.to, Medium, or future platforms.
• Single source of truth: Readers always know where to find the authoritative version.

Adding a New Page

1. Create documentation/new-page.md with appropriate front matter.
2. Link from other pages using {{devto:new-page}}.
3. Commit and push to main.

The pipeline automatically deploys to GitHub Pages and syncs the new page to Dev.to.

Required Secrets and Variables

---

This infrastructure enables “write once, publish everywhere” for living documentation that evolves with the methodology.