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:
- Invoke
docs-managementskill for documentation patterns - Verify tooling versions via MCP servers (context7 for docusaurus/mkdocs)
- 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
- Use active voice: "Configure the setting" not "The setting should be configured"
- Be concise: Remove unnecessary words
- Use examples: Show, don't just tell
- Maintain consistency: Same terms throughout
- 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:
- Choose Tooling: Select SSG based on team skills and requirements
- Set Up Structure: Create organized folder hierarchy
- Configure CI/CD: Automated builds, previews, deployments
- Add Linting: Markdown linting, link checking, spell check
- Enable Reviews: PR-based workflow with tech writer review
- Deploy Versioning: Set up version management strategy
- Monitor Analytics: Track usage, search queries, gaps
References
For detailed guidance:
Last Updated: 2025-12-26