docs-as-code

# Docs-as-Code Skill ## When to Use This Skill Use this skill when: - **Docs As Code tasks** - Working on documentation pipeline automation and docs-as-code workflows - **Planning or design** - Need guidance on Docs As Code approaches - **Best practices** - Want to follow established patterns and standards ## Overview Implement documentation-as-code workflows with automated pipelines, version control, and CI/CD integration. ## MANDATORY: Documentation-First Approach Before implementing docs-as-code: 1. **Invoke `docs-management` skill** for documentation patterns 2. **Verify tooling versions** via MCP servers (context7 for docusaurus/mkdocs) 3. **Base guidance on current best practices** ## Docs-as-Code Philosophy ```text Docs-as-Code Principles: ┌─────────────────────────────────────────────────────────────────────────────┐ │ 1. Version Control │ │ - Docs live alongside code in the same repository │ │ - Changes tracked with meaningful commit messages │ │ - Branch-based workflow for documentation updates │ ├─────────────────────────────────────────────────────────────────────────────┤ │ 2. Review Process │ │ - Pull requests for documentation changes │ │ - Technical review by subject matter experts │ │ - Style review by technical writers │ ├─────────────────────────────────────────────────────────────────────────────┤ │ 3. Automated Testing │ │ - Linting for style and grammar │ │ - Link validation │ │ - Build verification │ ├─────────────────────────────────────────────────────────────────────────────┤ │ 4. Continuous Deployment │ │ - Automatic publishing on merge │ │ - Preview deployments for PRs │ │ - Versioned documentation releases │ └─────────────────────────────────────────────────────────────────────────────┘ ``` ## Documentation Tooling Comparison | Tool | Language | Best For | Build Speed | |------|----------|----------|-------------| | **Docusaurus** | JS/React | Product docs, versioning | Fast | | **MkDocs** | Python | Technical docs, Material theme | Fast | | **Sphinx** | Python | API docs, reStructuredText | Medium | | **Hugo** | Go | Large sites, speed | Very Fast | | **Astro** | JS | Modern sites, MDX | Fast | | **VitePress** | JS/Vue | Vue ecosystem | Very Fast | | **Jekyll** | Ruby | GitHub Pages native | Medium | ## Project Structure ### Docusaurus Structure ```text docs/ ├── docusaurus.config.js # Main configuration ├── sidebars.js # Navigation structure ├── package.json # Dependencies ├── docs/ # Documentation content │ ├── intro.md │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ ├── guides/ │ │ ├── quick-start.md │ │ └── advanced.md │ └── api/ │ └── reference.md ├── blog/ # Blog posts (optional) ├── src/ │ ├── components/ # React components │ ├── css/ # Custom styles │ └── pages/ # Custom pages ├── static/ # Static assets │ └── img/ └── versioned_docs/ # Version snapshots ├── version-1.0/ └── version-2.0/ ``` ### MkDocs Structure ```text docs/ ├── mkdocs.yml # Configuration ├── docs/ │ ├── index.md │ ├── getting-started/ │ │ ├── installation.md │ │ └── configuration.md │ ├── user-guide/ │ │ └── features.md │ ├── reference/ │ │ └── api.md │ └── about/ │ └── changelog.md ├── overrides/ # Theme customization │ ├── main.html │ └── partials/ └── requirements.txt # Python dependencies ``` ## Configuration Templates ### Docusaurus Configuration ```javascript // docusaurus.config.js const config = { title: 'Project Name', tagline: 'Project tagline', url: 'https://docs.example.com', baseUrl: '/', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', favicon: 'img/favicon.ico', organizationName: 'organization', projectName: 'project', i18n: { defaultLocale: 'en', locales: ['en'], }, presets: [ [ 'classic', { docs: { sidebarPath: require.resolve('./sidebars.js'), editUrl: 'https://github.com/org/project/edit/main/docs/', showLastUpdateAuthor: true, showLastUpdateTime: true, versions: { current: { label: 'Next', path: 'next', }, }, }, blog: { showReadingTime: true, editUrl: 'https://github.com/org/project/edit/main/docs/', }, theme: { customCss: require.resolve('./src/css/custom.css'), }, }, ], ], themeConfig: { navbar: { title: 'Project', logo: { alt: 'Project Logo', src: 'img/logo.svg', }, items: [ { type: 'doc', docId: 'intro', position: 'left', label: 'Docs' }, { to: '/blog', label: 'Blog', position: 'left' }, { type: 'docsVersionDropdown', position: 'right' }, { href: 'https://github.com/org/project', label: 'GitHub', position: 'right' }, ], }, footer: { style: 'dark', links: [ { title: 'Docs', items: [{ label: 'Getting Started', to: '/docs/intro' }], }, { title: 'Community', items: [{ label: 'Discord', href: 'https://discord.gg/xxx' }], }, ], copyright: `Copyright © ${new Date().getFullYear()} Organization.`, }, prism: { theme: require('prism-react-renderer/themes/github'), darkTheme: require('prism-react-renderer/themes/dracula'), additionalLanguages: ['csharp', 'powershell', 'bash'], }, algolia: { appId: 'YOUR_APP_ID', apiKey: 'YOUR_SEARCH_API_KEY', indexName: 'project', }, }, }; module.exports = config; ``` ### MkDocs Configuration ```yaml # mkdocs.yml site_name: Project Documentation site_url: https://docs.example.com repo_url: https://github.com/org/project repo_name: org/project edit_uri: edit/main/docs/ theme: name: material palette: - scheme: default primary: indigo accent: indigo toggle: icon: material/brightness-7 name: Switch to dark mode - scheme: slate primary: indigo accent: indigo toggle: icon: material/brightness-4 name: Switch to light mode features: - navigation.instant - navigation.tracking - navigation.tabs - navigation.sections - navigation.expand - navigation.indexes - toc.follow - content.code.copy - content.code.annotate - search.suggest - search.highlight plugins: - search - git-revision-date-localized: enable_creation_date: true - minify: minify_html: true - mike: version_selector: true css_dir: css javascript_dir: js markdown_extensions: - pymdownx.highlight: anchor_linenums: true - pymdownx.superfences: custom_fences: - name: mermaid class: mermaid format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true - admonition - pymdownx.details - attr_list - md_in_html - toc: permalink: true nav: - Home: index.md - Getting Started: - Installation: getting-started/installation.md - Configuration: getting-started/configuration.md - User Guide: - Features: user-guide/features.md - Reference: - API: reference/api.md - About: - Changelog: about/changelog.md extra: version: provider: mike social: - icon: fontawesome/brands/github link: https://github.com/org/project ``` ## CI/CD Pipeline Templates ### GitHub Actions for Docusaurus ```yaml # .github/workflows/docs.yml name: Documentation on: push: branches: [main] paths: - 'docs/**' - '.github/workflows/docs.yml' pull_request: branches: [main] paths: - 'docs/**' jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' cache-dependency-path: docs/package-lock.json - name: Install dependencies working-directory: docs run: npm ci - name: Lint Markdown run: npx markdownlint-cli2 "docs/**/*.md" - name: Check links working-directory: docs run: npm run check-links build: runs-on: ubuntu-latest needs: lint steps: - uses: actions/checkout@v5 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' cache: 'npm' cache-dependency-path: docs/package-lock.json - name: Install dependencies working-directory: docs run: npm ci - name: Build working-directory: docs run: npm run build - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: path: docs/build deploy: if: github.ref == 'refs/heads/main' needs: build runs-on: ubuntu-latest permissions: pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 preview: if: github.event_name == 'pull_request' needs: build runs-on: ubuntu-latest steps: - name: Deploy preview uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: docs/build destination_dir: pr-preview/${{ github.event.number }} - name: Comment preview URL uses: actions/github-script@v7 with: script: | github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: '📚 Documentation preview: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/${{ github.event.number }}/' }) ``` ### Azure DevOps for MkDocs ```yaml # azure-pipelines.yml trigger: branches: include: - main paths: include: - docs/** pool: vmImage: 'ubuntu-latest' variables: pythonVersion: '3.11' stages: - stage: Validate jobs: - job: Lint steps: - task: UsePythonVersion@0 inputs: versionSpec: '$(pythonVersion)' - script: | pip install -r docs/requirements.txt pip install markdownlint-cli2 displayName: 'Install dependencies' - script: markdownlint-cli2 "docs/**/*.md" displayName: 'Lint Markdown' - stage: Build dependsOn: Validate jobs: - job: Build steps: - task: UsePythonVersion@0 inputs: versionSpec: '$(pythonVersion)' - script: pip install -r docs/requirements.txt displayName: 'Install dependencies' - script: mkdocs build --strict displayName: 'Build documentation' - publish: site artifact: documentation - stage: Deploy dependsOn: Build condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main')) jobs: - deployment: Deploy environment: production strategy: runOnce: deploy: steps: - download: current artifact: documentation - task: AzureStaticWebApp@0 inputs: app_location: '$(Pipeline.Workspace)/documentation' azure_static_web_apps_api_token: $(AZURE_STATIC_WEB_APPS_TOKEN) ``` ## Documentation Linting ### Markdownlint Configuration ```json // .markdownlint.json { "default": true, "MD001": true, "MD003": { "style": "atx" }, "MD004": { "style": "dash" }, "MD007": { "indent": 2 }, "MD009": true, "MD010": true, "MD012": true, "MD013": { "line_length": 120, "code_blocks": false, "tables": false }, "MD022": { "lines_above": 1, "lines_below": 1 }, "MD024": { "siblings_only": true }, "MD025": { "front_matter_title": "" }, "MD026": { "punctuation": ".,;:!" },