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

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

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

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

// 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

# 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

# .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

# 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

// .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": ".,;:!" },
  "MD029": { "style": "ordered" },
  "MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 },
  "MD033": { "allowed_elements": ["details", "summary", "kbd", "br"] },
  "MD035": { "style": "---" },
  "MD036": false,
  "MD040": true,
  "MD041": true,
  "MD046": { "style": "fenced" },
  "MD048": { "style": "backtick" }
}

Vale Configuration

# .vale.ini
StylesPath = styles

MinAlertLevel = suggestion

Packages = Microsoft, write-good, proselint

[*.md]
BasedOnStyles = Vale, Microsoft, write-good

# Ignore code blocks
BlockIgnores = (?s) *(`{3}.*?`{3})

# Custom rules
Microsoft.Contractions = NO
Microsoft.HeadingPunctuation = YES
write-good.Passive = YES
write-good.Weasel = YES
write-good.TooWordy = YES

Living Documentation

Generating API Docs from Code

// API Documentation Generation with XML Comments
/// <summary>
/// Manages user authentication and authorization.
/// </summary>
/// <remarks>
/// <para>
/// This service handles all authentication flows including:
/// <list type="bullet">
///   <item>Password-based authentication</item>
///   <item>OAuth 2.0 / OpenID Connect</item>
///   <item>API key authentication</item>
/// </list>
/// </para>
/// </remarks>
/// <example>
/// <code>
/// var result = await authService.AuthenticateAsync(credentials);
/// if (result.IsSuccess)
/// {
///     var token = result.Value.AccessToken;
/// }
/// </code>
/// </example>
public interface IAuthenticationService
{
    /// <summary>
    /// Authenticates a user with the provided credentials.
    /// </summary>
    /// <param name="credentials">The authentication credentials.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>
    /// A result containing the authentication response on success,
    /// or an error on failure.
    /// </returns>
    /// <exception cref="AuthenticationException">
    /// Thrown when authentication fails due to invalid credentials.
    /// </exception>
    Task<Result<AuthenticationResponse>> AuthenticateAsync(
        AuthenticationCredentials credentials,
        CancellationToken cancellationToken = default);
}

OpenAPI Documentation Generation

// Program.cs - Swagger/OpenAPI configuration
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "Project API",
        Version = "v1",
        Description = "API documentation for the Project",
        Contact = new OpenApiContact
        {
            Name = "API Support",
            Email = "api@example.com",
            Url = new Uri("https://docs.example.com")
        },
        License = new OpenApiLicense
        {
            Name = "MIT",
            Url = new Uri("https://opensource.org/licenses/MIT")
        }
    });

    // Include XML comments
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);

    // Security definitions
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        Description = "JWT Authorization header using the Bearer scheme.",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.Http,
        Scheme = "bearer"
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            Array.Empty<string>()
        }
    });
});

Documentation Testing

Link Checking

// check-links.mjs
import { remark } from 'remark';
import remarkLintNoDeadUrls from 'remark-lint-no-dead-urls';
import { read } from 'to-vfile';
import { glob } from 'glob';
import { reporter } from 'vfile-reporter';

const files = await glob('docs/**/*.md');

for (const file of files) {
  const result = await remark()
    .use(remarkLintNoDeadUrls, {
      skipLocalhost: true,
      skipOffline: true,
    })
    .process(await read(file));

  console.error(reporter(result));
}

Screenshot Testing

// docs.spec.ts - Playwright screenshot tests
import { test, expect } from '@playwright/test';

test.describe('Documentation Screenshots', () => {
  test('homepage renders correctly', async ({ page }) => {
    await page.goto('/');
    await expect(page).toHaveScreenshot('homepage.png');
  });

  test('API reference page', async ({ page }) => {
    await page.goto('/docs/api/reference');
    await expect(page.locator('.api-content')).toBeVisible();
    await expect(page).toHaveScreenshot('api-reference.png');
  });

  test('dark mode toggle', async ({ page }) => {
    await page.goto('/');
    await page.click('[data-theme-toggle]');
    await expect(page).toHaveScreenshot('homepage-dark.png');
  });
});

Best Practices

Content Organization

Practice	Description
Single Source of Truth	Each concept documented in one place
Progressive Disclosure	Start simple, link to details
Consistent Structure	Same sections across similar pages
Clear Navigation	Logical hierarchy, breadcrumbs
Search Optimization	Good headings, keywords, descriptions

Writing Guidelines

1. Use active voice: "Configure the setting" not "The setting should be configured"
2. Be concise: Remove unnecessary words
3. Use examples: Show, don't just tell
4. Maintain consistency: Same terms throughout
5. Update regularly: Documentation rots quickly

Versioning Strategy

Documentation Versioning:

Option 1: Version Folders (Docusaurus/MkDocs mike)
├── docs/
│   ├── version-1.0/
│   ├── version-2.0/
│   └── current/

Option 2: Branch-based
├── main (current)
├── v1.x
└── v2.x

Option 3: Git Tags
├── v1.0.0
├── v2.0.0
└── latest

Recommendation: Use tool-native versioning (Docusaurus versioned_docs, mike for MkDocs)

Workflow

When implementing docs-as-code:

1. Choose Tooling: Select SSG based on team skills and requirements
2. Set Up Structure: Create organized folder hierarchy
3. Configure CI/CD: Automated builds, previews, deployments
4. Add Linting: Markdown linting, link checking, spell check
5. Enable Reviews: PR-based workflow with tech writer review
6. Deploy Versioning: Set up version management strategy
7. Monitor Analytics: Track usage, search queries, gaps

References

For detailed guidance:

---

Last Updated: 2025-12-26