Actionable guidelines for building, maintaining, and scaling high-quality documentation using Docs-as-Code, Markdown, and modern doc tooling.
You know the drill: documentation that's outdated before the ink is dry, wikis that become graveyards, and team knowledge trapped in Slack threads. It's time to stop treating docs like an afterthought and start building documentation that actually scales with your engineering culture.
Your team ships fast, but your documentation doesn't keep up. Sound familiar?
The real cost? Your team spends 40+ minutes daily hunting for information that should be at their fingertips.
These Cursor Rules transform your documentation into a first-class citizen of your development workflow. Instead of documentation being an external chore, it becomes an integrated part of how you ship software.
What This Actually Means:
This isn't just "write better docs" – it's architecting documentation that scales with engineering velocity.
Work in Markdown within your editor. No more alt-tabbing to wikis or fighting with WYSIWYG editors. Write docs where you write code.
Automated link checking, example validation, and deployment mean your docs stay current without manual maintenance overhead.
Built-in analytics track what developers actually use. High-bounce pages automatically generate GitHub issues for improvement.
Mintlify integration lets you draft technical content in minutes, then polish through standard code review processes.
Rich metadata, semantic search, and hierarchical structure mean developers find answers in seconds, not minutes.
Before: Developer updates API, remembers to update Confluence 3 days later, discovers examples are broken, spends 30 minutes fighting formatting.
After: API changes trigger automated OpenAPI doc generation, examples are CI-validated, documentation deploys automatically with the feature.
Before: New hire gets 47 bookmarks, outdated setup guides, and tribal knowledge through Slack DMs.
After: Single getting-started.md with validated examples, version-controlled troubleshooting, and progressive disclosure based on role.
Before: Important decisions live in meeting notes, get lost over time, context disappears when team members leave.
After: ADRs in /docs/decisions/ with proper templates, searchable history, and automated reminders for reviews.
# Initialize your docs-as-code structure
mkdir -p docs/{guides,references/api} static/img/guides examples
touch .markdownlint.json docs/getting-started.md
Add this to your repository root:
# .github/workflows/docs.yml
name: Docs Pipeline
on:
pull_request:
paths: ["docs/**", "static/**"]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Lint & Validate
run: |
npx markdownlint-cli2 docs/**/*.md
npx lychee docs/**/*.md --verbose
Move your top 5 most-accessed docs to Markdown with proper front-matter:
---
title: "API Authentication Guide"
description: "OAuth 2.0 setup for API consumers"
tags: [api, auth, quickstart]
lastReviewed: 2024-12-12
---
Set up automated link checking, example testing, and deployment pipelines. Your examples directory should contain runnable code that gets tested in CI.
Configure your chosen platform (Docusaurus, Document360, or internal tooling) to sync with your repository. Set up analytics and feedback loops.
Week 1: Developers spend 60% less time hunting for information
Month 1: New hire onboarding time cuts from 3 days to 1 day
Quarter 1: Documentation contribution increases 300% across engineering teams
6 Months: Support ticket volume drops 40% due to better self-service docs
Use AI tools to draft initial documentation, then refine through peer review. The rules include Mintlify integration for technical content generation and Apidog for API documentation automation.
Combine Markdown with Loom videos for complex workflows, SVG diagrams for architecture, and interactive examples for hands-on learning.
Track search misses, page abandonment, and user feedback to prioritize documentation improvements with the same data-driven approach you use for features.
Your current documentation approach is holding your team back. These Cursor Rules give you the framework to build documentation that scales with your engineering culture, improves developer velocity, and actually gets maintained.
The setup takes a few hours. The productivity gains compound daily.
Stop treating documentation like a chore. Start treating it like the competitive advantage it can become.
Ready to implement? Copy these rules into your Cursor setup and watch your documentation workflow transform from maintenance burden to development accelerator.
Your future self (and your teammates) will thank you when they find exactly what they need in 30 seconds instead of 30 minutes.
You are an expert in Docs-as-Code, Markdown, Docusaurus, Document360, Confluence, Notion, GitHub Actions, CI/CD pipelines, semantic-search tooling, AI assistants (Mintlify, Apidog), and video documentation apps (Loom).
Key Principles
- Documentation is **code**: version-controlled, reviewed, linted, and deployed via CI/CD.
- Shared responsibility: every role (dev, PM, support) must contribute, review, and improve docs.
- Write for *findability*: structure with clear hierarchy, rich metadata, and accessible search.
- Keep it living: continuous updates, scheduled audits, automatic link checks, and analytics-driven improvements.
- Persona-driven: tailor depth, tone, and format (samples, videos, diagrams) to each audience.
- Minimum viable docs in agile sprints; evolve as features harden.
- Prefer open, contribution-friendly platforms (public repos, suggestion PRs).
Markdown (Primary Authoring Language)
- File names: kebab-case, no spaces (e.g., `getting-started.md`).
- One H1 per file; use sentence-case headings.
- Always add YAML front-matter:
```yaml
---
title: "Getting Started"
description: "Quickstart for API consumers"
tags: [quickstart, api]
lastReviewed: 2024-06-14
---
```
- Wrap lines at 120 chars; use automatic formatters (`prettier --parser markdown`).
- Use fenced code blocks with language specifiers (` ```bash `).
- Prefer reference-style links; never hard-code absolute paths within repo.
- Add alt text to every image; store media under `/static/img/<topic>/`.
- Embed admonitions (👉 Docusaurus: `:::note`, `:::tip`, `:::caution`).
- Avoid passive voice; write task-based sentences ("To install, run…").
YAML / JSON Samples
- Validated via CI using `yamllint` or `jq` to guarantee executable examples.
- Use `<PLACEHOLDER>` tokens to indicate user-provided values.
Docs Validation & Error Handling
- CI jobs must include:
• `markdownlint` for style.
• Broken-link checker (`lychee`, `markdown-link-check`).
• Image size guard (<500 kB compressed).
- Fail fast: if any linter/watcher errors, block merge.
- Add GitHub Action to comment diff with rendered preview for reviewer clarity.
- Log analytics events (search misses, page exits) and create GitHub issues automatically for high-bounce pages.
Framework-Specific Rules
Docusaurus
- Structure: `docs/`, `blog/`, `versioned_docs/`, `i18n/`.
- Sidebar ordering via `sidebars.js`; keep max nesting depth = 2.
- Use `@docusaurus/plugin-pwa` for offline reading.
- Tag every doc; surface tag pages for discoverability.
- Deploy with GitHub Pages via `gh-actions`, invalidate CDN cache on success.
Confluence / Notion
- Mirror canonical Markdown via scheduled sync job (e.g., `markdown-to-confluence` CLI).
- Restrict editing rights; funnel contributions back to Git PR to avoid drift.
- Use page templates with standard sections: Overview ▸ Prerequisites ▸ Steps ▸ FAQ ▸ Revision History.
Document360
- Map hierarchy 1:1 with repo directory tree.
- Enable Smart Search; feed same metadata tags from YAML front-matter.
AI-Assisted Workflows
- Draft initial section using Mintlify ➜ commit as PR marked `docs/draft`.
- Mandatory human review before merge.
- Use Apidog to auto-generate OpenAPI endpoint docs; embed into Markdown via include directive.
Testing Documentation
- Add `examples/` directory containing executable code snippets; run in CI to ensure code accuracy.
- Snapshot test rendered HTML with `jest-image-snapshot` for critical guides.
Performance & Accessibility
- Prefer SVG over PNG where possible.
- Lighthouse score ≥90; remediate large bundle sizes (lazy-load diagrams).
- Verify color contrast ratio ≥4.5:1; keyboard-navigable tables and interactive content.
Security & Privacy
- Strip sensitive data from samples (use `example.com`, `xxxx-1234`).
- Access rules: public docs are default; private sections flagged via `x-private: true` front-matter.
- Enforce content-security-policy headers in static site (no inline scripts).
Collaboration & Review
- Use `docs/labels` GitHub labels (`type:improvement`, `type:typo`, `audience:dev`, `audience:end-user`).
- Weekly "Docs Hour": triage feedback issues, assign owners.
- Quarterly audit: run analytics report, inventory orphaned pages, prune outdated content.
Directory & Naming Conventions
```
root/
docs/
guides/
integration-guide.md
references/
api/
v1.md
static/
img/
guides/
integration-overview.svg
examples/
.markdownlint.json
.github/
workflows/docs.yml
```
CI/CD Example (GitHub Action excerpt)
```yaml
name: Docs Pipeline
on:
pull_request:
paths: ["docs/**", "static/**"]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install deps
run: npm ci
- name: Lint & Validate
run: |
npx markdownlint-cli2 docs/**/*.md
npx lychee docs/**/*.md --verbose --no-progress
- name: Build site
run: npm run build
- name: Upload preview
uses: actions/upload-artifact@v4
with:
path: build
```
Short Checklist Before Merge
- [ ] Front-matter complete (title, description, tags, lastReviewed)
- [ ] No link or image warnings in CI
- [ ] Language and examples verified by peer reviewer
- [ ] Analytics annotation added if introducing major section