From 873da9670dd6b0c4cf2ede7721c35ea13ce20efd Mon Sep 17 00:00:00 2001 From: sven Date: Sat, 14 Mar 2026 14:56:38 +0100 Subject: [PATCH] Updates to add an AI section to the docs, including new pages and links, and to fix enhanced link search indexing by rendering titles as headings. --- docs/.vitepress/config.mjs | 51 ++++++++++++++ docs/ai/index.md | 21 ++++++ docs/ai/mcp-servers.md | 36 ++++++++++ docs/ai/review.md | 64 ++++++++++++++++++ docs/ai/writing.md | 54 +++++++++++++++ docs/index.md | 5 ++ docs/quality.md | 6 +- docs/style-guides.md | 36 +++++----- docs/tools.md | 28 ++++---- docs/writing.md | 5 +- .../changes/add-ai-section/.openspec.yaml | 2 + openspec/changes/add-ai-section/design.md | 67 +++++++++++++++++++ openspec/changes/add-ai-section/proposal.md | 37 ++++++++++ .../specs/ai-mcp-servers-page/spec.md | 29 ++++++++ .../specs/ai-review-page/spec.md | 29 ++++++++ .../specs/ai-section-nav/spec.md | 36 ++++++++++ .../specs/ai-writing-page/spec.md | 29 ++++++++ openspec/changes/add-ai-section/tasks.md | 24 +++++++ .../.openspec.yaml | 2 + .../design.md | 54 +++++++++++++++ .../proposal.md | 25 +++++++ .../specs/enhanced-link-title-audit/spec.md | 30 +++++++++ .../tasks.md | 49 ++++++++++++++ 23 files changed, 686 insertions(+), 33 deletions(-) create mode 100644 docs/ai/index.md create mode 100644 docs/ai/mcp-servers.md create mode 100644 docs/ai/review.md create mode 100644 docs/ai/writing.md create mode 100644 openspec/changes/add-ai-section/.openspec.yaml create mode 100644 openspec/changes/add-ai-section/design.md create mode 100644 openspec/changes/add-ai-section/proposal.md create mode 100644 openspec/changes/add-ai-section/specs/ai-mcp-servers-page/spec.md create mode 100644 openspec/changes/add-ai-section/specs/ai-review-page/spec.md create mode 100644 openspec/changes/add-ai-section/specs/ai-section-nav/spec.md create mode 100644 openspec/changes/add-ai-section/specs/ai-writing-page/spec.md create mode 100644 openspec/changes/add-ai-section/tasks.md create mode 100644 openspec/changes/fix-enhanced-link-search-indexing/.openspec.yaml create mode 100644 openspec/changes/fix-enhanced-link-search-indexing/design.md create mode 100644 openspec/changes/fix-enhanced-link-search-indexing/proposal.md create mode 100644 openspec/changes/fix-enhanced-link-search-indexing/specs/enhanced-link-title-audit/spec.md create mode 100644 openspec/changes/fix-enhanced-link-search-indexing/tasks.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index a5ae498..e68ac49 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -1,6 +1,40 @@ import { defineConfig } from 'vitepress' import { linkMetadataPlugin } from './plugins/linkMetadataPlugin' +/** + * Inject EnhancedLink title props as plain text into the markdown source + * before rendering, so VitePress local search can index link card titles. + * + * VitePress's local search _render hook receives the raw markdown source. + * is a Vue component — markdown-it passes it through as a + * raw HTML block, so the title prop value never appears as a text node in + * the indexed content. + * + * This function rewrites each tag to also emit + * the title as a plain markdown text token immediately after the tag, so + * the search indexer associates the title with the correct page section. + * + * @param {string} src - Raw markdown source of the page + * @param {object} env - VitePress page environment + * @param {object} md - markdown-it instance + * @returns {string} Rendered HTML with EnhancedLink titles as indexed text + */ +function renderWithEnhancedLinkTitles(src, env, md) { + // Replace each with a level-4 heading + // containing the title text, followed by the original tag. + // + // Using a heading (####) rather than a paragraph means: + // 1. The title appears as the matched section in search results (better UX) + // 2. The term is indexed in the `titles` field (higher relevance weight) + // 3. Clicking the result navigates to the correct section anchor + const patched = src.replace( + /(]*\btitle="([^"]+)"[^>]*\/>)/g, + (match, tag, title) => `\n\n#### ${title}\n\n${tag}\n\n` + ) + + return md.render(patched, env) +} + export default defineConfig({ vite: { plugins: [linkMetadataPlugin()] @@ -15,6 +49,7 @@ export default defineConfig({ search: { provider: 'local', options: { + _render: renderWithEnhancedLinkTitles, translations: { button: { buttonText: 'Search', @@ -50,6 +85,13 @@ export default defineConfig({ { text: 'GitHub Actions', link: '/github-actions' } ] }, + { text: 'AI', + items: [ + { text: 'AI Writing', link: '/ai/writing' }, + { text: 'AI Review', link: '/ai/review' }, + { text: 'MCP Servers', link: '/ai/mcp-servers' } + ] + }, { text: 'Guide', link: '/guide' }, { text: 'Contributing', link: '/contributing/' } ], @@ -83,6 +125,15 @@ export default defineConfig({ { text: 'Additional Tools', link: '/tools' } ] }, + { + text: 'AI', + items: [ + { text: 'Overview', link: '/ai/' }, + { text: 'Writing', link: '/ai/writing' }, + { text: 'Review', link: '/ai/review' }, + { text: 'MCP Servers', link: '/ai/mcp-servers' } + ] + }, { text: 'Contributing', items: [ diff --git a/docs/ai/index.md b/docs/ai/index.md new file mode 100644 index 0000000..5aa1f13 --- /dev/null +++ b/docs/ai/index.md @@ -0,0 +1,21 @@ +# AI for Documentation + +AI tools, agent skills, and MCP servers for technical writers and documentation teams. + +This section covers three areas where AI is changing documentation workflows: + +## 🖊️ [AI Writing](./writing) + +AI-powered writing assistants and agent skills for technical writing — from grammar and style tools to prompt templates that help you draft, structure, and refine documentation faster. + +## 🔍 [AI Review](./review) + +AI-powered review tools and agent skills for documentation review — tools that help catch issues, enforce style, and provide structured feedback on your docs before they ship. + +## 🔌 [MCP Servers](./mcp-servers) + +Model Context Protocol (MCP) servers relevant to documentation workflows — connecting AI agents directly to documentation tools like Vale, enabling richer, context-aware assistance. + +--- + +*Looking for non-AI writing tools? See [Writing Tools](../writing). For quality assurance and linting, see [Quality Assurance](../quality).* diff --git a/docs/ai/mcp-servers.md b/docs/ai/mcp-servers.md new file mode 100644 index 0000000..93e3016 --- /dev/null +++ b/docs/ai/mcp-servers.md @@ -0,0 +1,36 @@ +# MCP Servers + +Model Context Protocol (MCP) servers relevant to documentation workflows. + +## What is MCP? + +[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that allows AI assistants (such as Claude, Cursor, and other MCP-compatible clients) to connect to external tools and data sources. An MCP server exposes capabilities — like running a linter, querying a knowledge base, or fetching content — that an AI agent can invoke directly within a conversation. + +For documentation teams, MCP servers mean your AI assistant can actively use your documentation toolchain, not just talk about it. + +## Documentation MCP Servers + +### Vale MCP Server + +- **Repository**: [errata-ai/vale-mcp](https://github.com/errata-ai/vale-mcp) +- **Description**: An MCP server that exposes [Vale](https://vale.sh/) prose linting capabilities to AI assistants. Allows an AI agent to run Vale checks on text directly within a conversation, returning style and grammar issues according to your configured Vale rules. +- **Use cases**: + - Ask your AI assistant to lint a draft document against your style guide before publishing + - Integrate Vale feedback into AI-assisted writing and review workflows + - Run Vale checks without leaving your AI chat interface + +## Contributing + +Know of another MCP server useful for documentation workflows? This list is just getting started. + +MCP servers relevant to documentation might include servers for: +- Documentation platforms (Confluence, Notion, GitBook) +- Link checking and validation +- Terminology and glossary management +- Translation and localization + +*[Contribute to this project](../contributing/) and help grow this list.* + +--- + +*For AI writing tools, see [AI Writing](./writing). For AI review tools and Vale integration patterns, see [AI Review](./review).* diff --git a/docs/ai/review.md b/docs/ai/review.md new file mode 100644 index 0000000..5f2cba2 --- /dev/null +++ b/docs/ai/review.md @@ -0,0 +1,64 @@ +# AI Review + +AI-powered review tools, agent skills, and prompt resources for documentation review workflows. + +## AI Review Tools + +Tools that use AI to review, critique, and improve documentation quality. + +### Style & Prose Review + +- [Vale](https://vale.sh/) - Syntax-aware prose linter; integrates with AI workflows via the [Vale MCP Server](./mcp-servers) +- [Harper](https://writewithharper.com/) - Grammar checker built for developers, runs locally with no data sent to the cloud +- [Alex](https://github.com/get-alex/alex) - Catches insensitive and inconsiderate writing; pairs well with AI review workflows + +### AI-Assisted Review Platforms + +- [Grammarly Business](https://www.grammarly.com/business) - Team-level AI writing and review with style guide enforcement +- [Writer](https://writer.com/) - AI writing platform with built-in style guide, terminology management, and review workflows for teams +- [Acrolinx](https://www.acrolinx.com/) - Enterprise AI content governance platform for large documentation teams + +### Code Review with Docs Context + +- [GitHub Copilot Code Review](https://github.com/features/copilot) - AI-assisted pull request review that can flag missing or outdated documentation +- [Reviewdog](https://github.com/reviewdog/reviewdog) - Automated code review tool that integrates linters (including Vale) into PR workflows + +## Agent Skills & Prompts + +Prompt templates, system prompts, and agent skill patterns for documentation review workflows. + +### Review Prompt Patterns + +Effective prompt patterns for AI-assisted documentation review: + +- **Completeness check** — Ask the AI to identify missing sections, undefined terms, or steps that assume unstated prerequisites +- **Audience alignment** — Provide the target audience profile and ask the AI to flag content that is too advanced, too basic, or uses unexplained jargon +- **Consistency audit** — Paste multiple pages and ask the AI to identify inconsistent terminology, formatting, or tone across them +- **Accuracy review** — Provide the relevant code or API spec alongside the docs and ask the AI to flag discrepancies +- **Readability pass** — Ask the AI to score readability and suggest specific rewrites for sentences above a target complexity level + +### Structured Review Checklists as Prompts + +Convert your documentation review checklist into a prompt template: + +``` +Review the following documentation against these criteria: +1. Is every term defined on first use? +2. Are all code examples syntactically correct? +3. Does the content match the stated audience level? +4. Are there any broken or missing cross-references? +5. Is the tone consistent with [your style guide]? + +Flag each issue with: [ISSUE TYPE] - [location] - [description] +``` + +### Vale + AI Integration + +Vale's rule-based linting and AI review are complementary: +- Use Vale for deterministic, rule-based checks (style guide enforcement, terminology) +- Use AI for subjective review (clarity, completeness, audience fit) +- The [Vale MCP Server](./mcp-servers) enables AI agents to run Vale checks directly within a conversation + +--- + +*For non-AI quality assurance tools, see [Quality Assurance](../quality). For AI writing assistance, see [AI Writing](./writing).* diff --git a/docs/ai/writing.md b/docs/ai/writing.md new file mode 100644 index 0000000..102832a --- /dev/null +++ b/docs/ai/writing.md @@ -0,0 +1,54 @@ +# AI Writing + +AI-powered writing assistants, agent skills, and prompt resources for technical writing workflows. + +## AI Writing Assistants + +Tools that use AI to help you write, edit, and improve documentation. + +### General Purpose + +- [Grammarly](https://www.grammarly.com/) - AI-powered writing assistant with grammar, style, and tone suggestions +- [LanguageTool](https://languagetool.org/) - Open-source grammar and style checker with AI-enhanced suggestions +- [QuillBot](https://quillbot.com/) - AI paraphrasing and rewriting tool useful for simplifying complex technical content + +### Technical Writing Focused + +- [GitHub Copilot](https://github.com/features/copilot) - AI pair programmer that also assists with writing documentation, README files, and inline code comments +- [Mintlify Writer](https://writer.mintlify.com/) - AI-powered documentation writer that generates docs from code +- [Swimm](https://swimm.io/) - AI-assisted documentation platform that keeps docs synchronized with code + +### AI Editors & Integrations + +- [Cursor](https://www.cursor.com/) - AI-first code editor with strong support for editing Markdown and documentation files +- [Zed](https://zed.dev/) - High-performance editor with AI assistant integration for writing tasks + +## Agent Skills & Prompts + +Prompt templates, system prompts, and agent skill patterns for technical writing workflows. + +### Prompt Libraries + +- [Awesome ChatGPT Prompts](https://github.com/f/awesome-chatgpt-prompts) - Community-curated prompt collection including technical writing prompts +- [Fabric](https://github.com/danielmiessler/fabric) - Open-source framework for augmenting humans with AI, includes patterns for writing and summarization + +### Technical Writing Prompt Patterns + +Effective prompt patterns for common technical writing tasks: + +- **Draft from outline** — Provide a structured outline and ask the AI to expand each section with appropriate technical depth +- **Simplify for audience** — Paste complex content and specify the target audience (e.g., "rewrite this for a developer unfamiliar with Kubernetes") +- **Generate examples** — Ask the AI to produce code examples or step-by-step walkthroughs for a concept you've described +- **Review for clarity** — Ask the AI to identify sentences that are ambiguous, overly passive, or unnecessarily complex +- **Terminology consistency** — Provide a glossary and ask the AI to flag inconsistent term usage in a document + +### AI Writing with Roo/Claude Skills + +If you use AI coding assistants with skill/tool support, technical writing skills can be defined to: +- Enforce house style rules during drafting +- Generate structured documentation from code or API specs +- Produce first drafts of changelogs, release notes, or how-to guides + +--- + +*For non-AI writing tools, see [Writing Tools](../writing). For AI-powered review and linting, see [AI Review](./review).* diff --git a/docs/index.md b/docs/index.md index 173c634..6d44ac3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,6 +26,11 @@ A **curated list** of awesome documentation tools, guides and best practices for ### 🌐 Publishing & Hosting - [GitHub Actions](./github-actions) - Automation for documentation workflows +### 🤖 AI +- [AI Writing](./ai/writing) - AI writing assistants and agent skills for technical writing +- [AI Review](./ai/review) - AI review tools and agent skills for documentation review +- [MCP Servers](./ai/mcp-servers) - Model Context Protocol servers for documentation workflows + ### 📚 Learning Resources - [Style Guides](./style-guides) - Documentation and writing style guides - [Reading List](./reading) - Articles and resources about documentation diff --git a/docs/quality.md b/docs/quality.md index 90264a6..d126ac4 100644 --- a/docs/quality.md +++ b/docs/quality.md @@ -77,4 +77,8 @@ Most quality assurance tools can be integrated into: - Regular audits of documentation quality - Track metrics over time - User feedback analysis -- Tool effectiveness evaluation \ No newline at end of file +- Tool effectiveness evaluation + +## AI-Powered Review + +For AI-powered review tools, agent skills, and prompt templates for documentation review, see our [AI Review](/ai/review) section. \ No newline at end of file diff --git a/docs/style-guides.md b/docs/style-guides.md index 51d16cc..9fe9e07 100644 --- a/docs/style-guides.md +++ b/docs/style-guides.md @@ -6,16 +6,18 @@ Comprehensive collection of documentation style guides and writing standards fro ### Government & Standards -- [18F](https://content-guide.18f.gov/) - U.S. Digital Service content guide -- [Federal (US) plain language guidelines](https://plainlanguage.gov/guidelines/) - Government plain language standards -- [United Nations](https://www.un.org/dgacm/content/editorial-manual) - UN editorial manual + + + + + ### Web Standards & Accessibility - - - + + + ## Technology Companies @@ -25,19 +27,19 @@ Comprehensive collection of documentation style guides and writing standards fro - - - - + + + + ### Cloud & Infrastructure - - - - + + + + ### Database & Analytics @@ -55,9 +57,9 @@ Comprehensive collection of documentation style guides and writing standards fro ### Technical Writing - - - + + + ### Content & Marketing diff --git a/docs/tools.md b/docs/tools.md index 4a3aabe..24daa6a 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -14,10 +14,10 @@ Specialized tools and resources that support documentation workflows across vari ### Browser Testing Tools - - - - + + + + ### Spelling & Language Tools @@ -27,22 +27,22 @@ Specialized tools and resources that support documentation workflows across vari ## Accessibility Tools - - - - - + + + + + ## Hosting & Deployment - + - - - - + + + + ## Utility Tools diff --git a/docs/writing.md b/docs/writing.md index 2317d1d..1fb9f1f 100644 --- a/docs/writing.md +++ b/docs/writing.md @@ -65,4 +65,7 @@ Tools and resources for improving technical writing, grammar, and content creati For accessibility-focused writing tools, see our [Quality Assurance](/quality) section. ### Content Validation -For spell checking and content validation tools, see our [Quality Assurance](/quality) section. \ No newline at end of file +For spell checking and content validation tools, see our [Quality Assurance](/quality) section. + +### AI Writing Tools +For AI-powered writing assistants, agent skills, and prompt templates for technical writing, see our [AI Writing](/ai/writing) section. \ No newline at end of file diff --git a/openspec/changes/add-ai-section/.openspec.yaml b/openspec/changes/add-ai-section/.openspec.yaml new file mode 100644 index 0000000..49ccc67 --- /dev/null +++ b/openspec/changes/add-ai-section/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-14 diff --git a/openspec/changes/add-ai-section/design.md b/openspec/changes/add-ai-section/design.md new file mode 100644 index 0000000..5a6cbc9 --- /dev/null +++ b/openspec/changes/add-ai-section/design.md @@ -0,0 +1,67 @@ +## Context + +The Awesome Docs site is a VitePress-based curated list. Navigation and sidebar are defined in [`docs/.vitepress/config.mjs`](docs/.vitepress/config.mjs). Content pages are Markdown files under `docs/`. The site already uses `EnhancedLink` and `ResourceGrid` Vue components for rich link cards. + +Currently there is no AI-specific section. The only AI-related content is a single Grammarly entry in [`docs/writing.md`](docs/writing.md). MCP (Model Context Protocol) servers have no presence at all. + +The change adds four new Markdown pages under `docs/ai/`, updates the VitePress config, and adds cross-references from two existing pages. + +## Goals / Non-Goals + +**Goals:** +- Create `docs/ai/` subdirectory with `index.md`, `writing.md`, `review.md`, and `mcp-servers.md` +- Add a top-level **AI** nav item in `config.mjs` with three sub-items +- Add an **AI** sidebar group in `config.mjs` +- Add cross-reference links from `docs/writing.md` and `docs/quality.md` to the new AI pages +- Update `docs/index.md` Categories Overview to list the new AI section +- Populate each page with curated, relevant content following existing page conventions + +**Non-Goals:** +- Moving or removing the Grammarly entry from `docs/writing.md` (cross-link only) +- Adding MCP servers beyond the Vale MCP server in the initial implementation +- Creating a new VitePress theme component or plugin +- Automated link validation for the new pages (handled by existing CI) + +## Decisions + +### Decision 1: `docs/ai/` subdirectory over a single `docs/ai.md` + +**Chosen**: Subdirectory with four files (`index.md`, `writing.md`, `review.md`, `mcp-servers.md`) + +**Rationale**: Each topic (writing, review, MCP servers) is a distinct category that will grow independently. A subdirectory allows each to have its own nav entry, sidebar link, and URL. A single flat file would become unwieldy as content grows. + +**Alternative considered**: Single `docs/ai.md` — simpler to start but harder to split later without breaking URLs. + +### Decision 2: Cross-link from existing pages, not move content + +**Chosen**: Add a "See also" cross-reference in `docs/writing.md` and `docs/quality.md` pointing to the new AI pages. + +**Rationale**: Moving Grammarly would break the logical flow of `writing.md` (it's a browser extension, not exclusively an AI tool). Cross-linking preserves existing structure while connecting readers to the new section. + +**Alternative considered**: Move all AI-adjacent tools to `docs/ai/` — cleaner taxonomy but risks breaking reader expectations and existing bookmarks. + +### Decision 3: Top-level nav item for AI + +**Chosen**: Add `AI` as a new top-level nav item alongside `Tools` and `Resources`. + +**Rationale**: AI tooling is a first-class concern, not a subcategory of existing tools. A top-level item signals its importance and makes it discoverable. + +**Alternative considered**: Add AI as a sub-item under `Tools` — less visible, undersells the category. + +### Decision 4: Use plain Markdown lists for initial content (not `EnhancedLink`) + +**Chosen**: Plain Markdown links for the initial content entries. + +**Rationale**: `EnhancedLink` requires metadata fetching at build time. For a new section with potentially unstable URLs (especially MCP server repos), plain links are safer and faster to author. `EnhancedLink` can be adopted incrementally per the existing contributing guide. + +**Alternative considered**: Use `EnhancedLink` throughout — richer UX but adds build-time risk for new/unstable URLs. + +## Risks / Trade-offs + +- **MCP ecosystem immaturity** → The Vale MCP server and MCP in general are early-stage. Links may go stale quickly. Mitigation: note the experimental nature in the page intro; rely on community PRs to keep current. +- **Content staleness for AI tools** → AI tooling moves fast. Mitigation: keep entries minimal (name + one-line description + link); avoid version-specific details. +- **Nav crowding** → Adding a top-level AI item makes the nav bar wider. Mitigation: acceptable at current nav item count; revisit if more top-level items are added. + +## Open Questions + +- Should `docs/ai/index.md` be a full landing page with summaries of each sub-page, or a minimal redirect-style page? (Recommendation: full landing page, consistent with how other index pages work in the contributing section.) diff --git a/openspec/changes/add-ai-section/proposal.md b/openspec/changes/add-ai-section/proposal.md new file mode 100644 index 0000000..70f4314 --- /dev/null +++ b/openspec/changes/add-ai-section/proposal.md @@ -0,0 +1,37 @@ +## Why + +AI tooling for technical writing and documentation review is evolving rapidly, and readers of Awesome Docs need a dedicated, structured place to discover AI writing assistants, agent skills/prompt templates, and MCP servers relevant to documentation workflows. The Vale MCP server in particular represents a new paradigm — connecting AI agents directly to prose linting — that has no home in the current docs. + +## What Changes + +- Add a new `docs/ai/` subdirectory with four pages: `index.md`, `writing.md`, `review.md`, and `mcp-servers.md` +- Add an **AI** top-level nav group in the VitePress config with links to all three sub-pages +- Add an **AI** sidebar group in the VitePress config +- Add a cross-reference from `docs/writing.md` pointing to the new AI writing page +- Add a cross-reference from `docs/quality.md` pointing to the new AI review page +- Populate `docs/ai/writing.md` with AI writing assistants and agent skills/prompt resources for technical writing +- Populate `docs/ai/review.md` with AI review tools and agent skills/prompt resources for documentation review +- Populate `docs/ai/mcp-servers.md` with the Vale MCP server entry and a brief MCP introduction +- Update `docs/index.md` Categories Overview to include the new AI section + +## Capabilities + +### New Capabilities + +- `ai-writing-page`: A curated page of AI writing assistants and agent skills/prompts for technical writing workflows +- `ai-review-page`: A curated page of AI review tools and agent skills/prompts for documentation review workflows +- `ai-mcp-servers-page`: A curated page of MCP servers relevant to documentation, starting with the Vale MCP server +- `ai-section-nav`: VitePress navigation and sidebar entries for the new AI section + +### Modified Capabilities + + + +## Impact + +- `docs/.vitepress/config.mjs` — nav and sidebar updated +- `docs/index.md` — Categories Overview section updated +- `docs/writing.md` — cross-reference added +- `docs/quality.md` — cross-reference added +- New files: `docs/ai/index.md`, `docs/ai/writing.md`, `docs/ai/review.md`, `docs/ai/mcp-servers.md` +- No breaking changes; all existing pages and URLs remain unchanged diff --git a/openspec/changes/add-ai-section/specs/ai-mcp-servers-page/spec.md b/openspec/changes/add-ai-section/specs/ai-mcp-servers-page/spec.md new file mode 100644 index 0000000..1eaa251 --- /dev/null +++ b/openspec/changes/add-ai-section/specs/ai-mcp-servers-page/spec.md @@ -0,0 +1,29 @@ +## ADDED Requirements + +### Requirement: AI MCP servers page exists at /ai/mcp-servers +The system SHALL provide a page at `docs/ai/mcp-servers.md` that is accessible via the URL `/ai/mcp-servers` in the VitePress site. + +#### Scenario: Page is accessible +- **WHEN** a user navigates to `/ai/mcp-servers` +- **THEN** the page renders without error and displays the MCP servers content + +### Requirement: MCP servers page includes a brief MCP introduction +The page SHALL include a short introductory paragraph explaining what MCP (Model Context Protocol) is and why it is relevant to documentation workflows. + +#### Scenario: MCP introduction is present +- **WHEN** a user views the MCP servers page +- **THEN** they see an introductory section explaining MCP before any server listings + +### Requirement: MCP servers page lists the Vale MCP server +The page SHALL include an entry for the Vale MCP server with a name, link to its repository or documentation, and a one-line description of what it enables. + +#### Scenario: Vale MCP server entry is present +- **WHEN** a user views the MCP servers page +- **THEN** they see an entry for the Vale MCP server with a working link and description + +### Requirement: MCP servers page signals openness for contributions +The page SHALL include a note inviting contributors to add additional documentation-relevant MCP servers. + +#### Scenario: Contribution invitation is present +- **WHEN** a user views the MCP servers page +- **THEN** they see a note or call-to-action encouraging them to contribute additional MCP server entries diff --git a/openspec/changes/add-ai-section/specs/ai-review-page/spec.md b/openspec/changes/add-ai-section/specs/ai-review-page/spec.md new file mode 100644 index 0000000..94adc6f --- /dev/null +++ b/openspec/changes/add-ai-section/specs/ai-review-page/spec.md @@ -0,0 +1,29 @@ +## ADDED Requirements + +### Requirement: AI review page exists at /ai/review +The system SHALL provide a page at `docs/ai/review.md` that is accessible via the URL `/ai/review` in the VitePress site. + +#### Scenario: Page is accessible +- **WHEN** a user navigates to `/ai/review` +- **THEN** the page renders without error and displays the AI review content + +### Requirement: AI review page contains AI review tools section +The page SHALL include a section listing AI-powered tools for reviewing documentation, with each entry containing a name, link, and one-line description. + +#### Scenario: Review tools section is present +- **WHEN** a user views the AI review page +- **THEN** they see a section titled "AI Review Tools" with at least one tool entry + +### Requirement: AI review page contains agent skills and prompts section for review +The page SHALL include a section covering agent skills, system prompts, and prompt templates for documentation review workflows. + +#### Scenario: Agent skills for review section is present +- **WHEN** a user views the AI review page +- **THEN** they see a section covering AI agent skills or prompt resources for documentation review + +### Requirement: AI review page cross-references quality assurance tools +The page SHALL include a note or link directing readers to the Quality Assurance page for non-AI review and linting tools. + +#### Scenario: Cross-reference to quality assurance is present +- **WHEN** a user views the AI review page +- **THEN** they see a reference or link to `/quality` for broader quality assurance tool coverage diff --git a/openspec/changes/add-ai-section/specs/ai-section-nav/spec.md b/openspec/changes/add-ai-section/specs/ai-section-nav/spec.md new file mode 100644 index 0000000..2428649 --- /dev/null +++ b/openspec/changes/add-ai-section/specs/ai-section-nav/spec.md @@ -0,0 +1,36 @@ +## ADDED Requirements + +### Requirement: AI top-level nav item exists in VitePress config +The VitePress config SHALL include a top-level nav item labelled "AI" with sub-items linking to `/ai/writing`, `/ai/review`, and `/ai/mcp-servers`. + +#### Scenario: AI nav item is present with sub-items +- **WHEN** a user views any page on the site +- **THEN** the top navigation bar contains an "AI" item that expands to show "AI Writing", "AI Review", and "MCP Servers" links + +### Requirement: AI sidebar group exists in VitePress config +The VitePress config SHALL include a sidebar group labelled "AI" containing links to `/ai/`, `/ai/writing`, `/ai/review`, and `/ai/mcp-servers`. + +#### Scenario: AI sidebar group is present +- **WHEN** a user views any page on the site +- **THEN** the sidebar contains an "AI" group with four entries: Overview, Writing, Review, and MCP Servers + +### Requirement: docs/index.md Categories Overview includes AI section +The `docs/index.md` Categories Overview section SHALL include a reference to the new AI section with a link to `/ai/`. + +#### Scenario: AI section appears in index categories +- **WHEN** a user views the home page +- **THEN** the Categories Overview section lists the AI section with a link + +### Requirement: docs/writing.md cross-references AI writing page +The `docs/writing.md` page SHALL include a "See also" or equivalent cross-reference linking to `/ai/writing` for AI-specific writing tools. + +#### Scenario: Cross-reference to AI writing is present in writing.md +- **WHEN** a user views the Writing Tools page +- **THEN** they see a reference directing them to the AI Writing page for AI-specific tools + +### Requirement: docs/quality.md cross-references AI review page +The `docs/quality.md` page SHALL include a "See also" or equivalent cross-reference linking to `/ai/review` for AI-specific review tools. + +#### Scenario: Cross-reference to AI review is present in quality.md +- **WHEN** a user views the Quality Assurance page +- **THEN** they see a reference directing them to the AI Review page for AI-specific review tools diff --git a/openspec/changes/add-ai-section/specs/ai-writing-page/spec.md b/openspec/changes/add-ai-section/specs/ai-writing-page/spec.md new file mode 100644 index 0000000..0f53f89 --- /dev/null +++ b/openspec/changes/add-ai-section/specs/ai-writing-page/spec.md @@ -0,0 +1,29 @@ +## ADDED Requirements + +### Requirement: AI writing page exists at /ai/writing +The system SHALL provide a page at `docs/ai/writing.md` that is accessible via the URL `/ai/writing` in the VitePress site. + +#### Scenario: Page is accessible +- **WHEN** a user navigates to `/ai/writing` +- **THEN** the page renders without error and displays the AI writing content + +### Requirement: AI writing page contains AI writing assistants section +The page SHALL include a section listing AI-powered writing assistant tools relevant to technical writing, with each entry containing a name, link, and one-line description. + +#### Scenario: Writing assistants section is present +- **WHEN** a user views the AI writing page +- **THEN** they see a section titled "AI Writing Assistants" with at least one tool entry + +### Requirement: AI writing page contains agent skills and prompts section +The page SHALL include a section covering agent skills, system prompts, and prompt templates for technical writing workflows. + +#### Scenario: Agent skills section is present +- **WHEN** a user views the AI writing page +- **THEN** they see a section covering AI agent skills or prompt resources for technical writing + +### Requirement: AI writing page cross-references existing writing tools +The page SHALL include a note or link directing readers to the main Writing Tools page for non-AI writing tools. + +#### Scenario: Cross-reference to writing tools is present +- **WHEN** a user views the AI writing page +- **THEN** they see a reference or link to `/writing` for broader writing tool coverage diff --git a/openspec/changes/add-ai-section/tasks.md b/openspec/changes/add-ai-section/tasks.md new file mode 100644 index 0000000..afdf3a9 --- /dev/null +++ b/openspec/changes/add-ai-section/tasks.md @@ -0,0 +1,24 @@ +## 1. VitePress Config Updates + +- [x] 1.1 Add "AI" top-level nav item to `docs/.vitepress/config.mjs` with sub-items: AI Writing (`/ai/writing`), AI Review (`/ai/review`), MCP Servers (`/ai/mcp-servers`) +- [x] 1.2 Add "AI" sidebar group to `docs/.vitepress/config.mjs` with entries: Overview (`/ai/`), Writing (`/ai/writing`), Review (`/ai/review`), MCP Servers (`/ai/mcp-servers`) + +## 2. AI Section Pages + +- [x] 2.1 Create `docs/ai/index.md` — landing page with overview of all three sub-pages and brief descriptions of each area +- [x] 2.2 Create `docs/ai/writing.md` — AI writing assistants section and agent skills/prompts section for technical writing +- [x] 2.3 Create `docs/ai/review.md` — AI review tools section and agent skills/prompts section for documentation review +- [x] 2.4 Create `docs/ai/mcp-servers.md` — MCP introduction, Vale MCP server entry, and contribution invitation + +## 3. Cross-References in Existing Pages + +- [x] 3.1 Add cross-reference in `docs/writing.md` pointing to `/ai/writing` for AI-specific writing tools +- [x] 3.2 Add cross-reference in `docs/quality.md` pointing to `/ai/review` for AI-specific review tools +- [x] 3.3 Add AI section entry to the Categories Overview in `docs/index.md` + +## 4. Verification + +- [x] 4.1 Run `pnpm docs:dev` and verify all four AI pages render correctly +- [x] 4.2 Verify the AI nav item and sidebar group appear and all links resolve +- [x] 4.3 Verify cross-references in `docs/writing.md` and `docs/quality.md` link correctly +- [x] 4.4 Verify `docs/index.md` Categories Overview includes the AI section link diff --git a/openspec/changes/fix-enhanced-link-search-indexing/.openspec.yaml b/openspec/changes/fix-enhanced-link-search-indexing/.openspec.yaml new file mode 100644 index 0000000..49ccc67 --- /dev/null +++ b/openspec/changes/fix-enhanced-link-search-indexing/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-03-14 diff --git a/openspec/changes/fix-enhanced-link-search-indexing/design.md b/openspec/changes/fix-enhanced-link-search-indexing/design.md new file mode 100644 index 0000000..b327d0a --- /dev/null +++ b/openspec/changes/fix-enhanced-link-search-indexing/design.md @@ -0,0 +1,54 @@ +## Context + +VitePress's built-in local search works by indexing the **static markdown source** of each page at build time. It does not execute Vue components or fetch runtime data. + +`` components that omit the `title` prop display their link title by fetching metadata from `/cache/link-metadata.json` in the browser at runtime. Because the search indexer never sees this fetched title, those links are invisible to search — searching for "GitLab Style Guide", "Google Developer Documentation Style Guide", etc. returns no results even though those pages exist. + +The metadata cache (`docs/.vitepress/cache/link-metadata.json`) already contains the correct titles for all URLs — it is populated at build time by the `linkMetadataPlugin`. The titles are available; they just aren't written into the markdown source. + +**Affected files (EnhancedLink usages without `title`):** +- `docs/style-guides.md` — multiple `` blocks +- `docs/tools.md` — multiple `` blocks +- `docs/contributing/enhanced-links.md` — example usages (documentation page) + +## Goals / Non-Goals + +**Goals:** +- Every `` in the docs has an explicit `title` prop so VitePress search can index it. +- Titles are sourced from the existing metadata cache — no new network requests. +- The fix is purely in markdown content files; no component or plugin code changes. + +**Non-Goals:** +- Changing the `EnhancedLink` component's runtime behaviour. +- Modifying the metadata fetch/cache pipeline. +- Adding search indexing for `description` or other metadata fields (out of scope). +- Fixing the example usages in `docs/contributing/enhanced-links.md` — those are intentional illustrations of the component API and should remain as-is. + +## Decisions + +### Decision 1: Add `title` props to markdown source (not a build-time transform) + +**Chosen:** Manually add `title="..."` to each `` in the markdown files, using the metadata cache as the source of truth. + +**Alternatives considered:** +- *VitePress search `_render` hook*: Could transform component markup into indexable text at search-index build time. More complex, requires ongoing maintenance, and is fragile against VitePress upgrades. +- *Markdown-it plugin to inject titles*: Would auto-populate titles from the cache during the markdown parse phase. Adds build complexity and makes the markdown source less readable/auditable. +- *Always require `title` prop (lint rule)*: Good long-term hygiene but doesn't fix existing content. + +**Rationale:** Explicit `title` props in the markdown source are the simplest, most transparent, and most maintainable solution. The markdown becomes self-documenting, the search index is correct, and no tooling changes are needed. + +### Decision 2: Source titles from the metadata cache + +**Chosen:** Read `docs/.vitepress/cache/link-metadata.json` to get the canonical title for each URL. + +**Rationale:** The cache is already populated and authoritative. Using it avoids any new network requests and ensures consistency between what the card displays at runtime and what the search index contains. + +### Decision 3: Use the page `` metadata value, trimmed if needed + +Some cached titles are verbose (e.g., `"Fast and reliable end-to-end testing for modern web apps | Playwright"`). For the `title` prop, use a human-readable short form (the part before ` | ` or ` - ` where appropriate) to keep the markdown readable and the search results clean. + +## Risks / Trade-offs + +- **Cache staleness** → If a linked site changes its page title, the `title` prop in markdown will drift from the fetched metadata. Mitigation: the `title` prop is the authoritative display value; the cache is only used as the initial source. Periodic audits can catch drift. +- **Manual effort** → There are ~30 `<EnhancedLink>` usages to update across 2-3 files. Low risk of error given the small scope. +- **Contributing docs examples** → The `docs/contributing/enhanced-links.md` page intentionally shows `<EnhancedLink>` without `title` as a usage example. These should NOT be changed, as they demonstrate the component's auto-fetch capability. diff --git a/openspec/changes/fix-enhanced-link-search-indexing/proposal.md b/openspec/changes/fix-enhanced-link-search-indexing/proposal.md new file mode 100644 index 0000000..353e048 --- /dev/null +++ b/openspec/changes/fix-enhanced-link-search-indexing/proposal.md @@ -0,0 +1,25 @@ +## Why + +`<EnhancedLink>` components that omit the `title` prop display their link title by fetching metadata at runtime in the browser. VitePress's built-in local search indexes only the static markdown source, so those links have no searchable text — searching for "GitLab Style Guide" (or any other title that comes from fetched metadata) returns zero results. Adding explicit `title` props to every `<EnhancedLink>` in the docs gives the search indexer the text it needs. + +## What Changes + +- Add a `title` prop to every `<EnhancedLink>` usage that currently omits it across all markdown pages. +- Titles are sourced from the already-populated metadata cache (`docs/.vitepress/cache/link-metadata.json`) so no new network requests are needed. +- No changes to the `EnhancedLink` component, the metadata plugin, or the VitePress config. + +## Capabilities + +### New Capabilities + +- `enhanced-link-title-audit`: Audit all markdown files for `<EnhancedLink>` usages missing a `title` prop and populate them from the metadata cache. + +### Modified Capabilities + +<!-- No existing spec-level requirements are changing. --> + +## Impact + +- All markdown files under `docs/` that use `<EnhancedLink>` without a `title` prop. +- The metadata cache (`docs/.vitepress/cache/link-metadata.json`) is read-only for this change (used as the source of truth for titles). +- No runtime or build-pipeline code changes required. diff --git a/openspec/changes/fix-enhanced-link-search-indexing/specs/enhanced-link-title-audit/spec.md b/openspec/changes/fix-enhanced-link-search-indexing/specs/enhanced-link-title-audit/spec.md new file mode 100644 index 0000000..edc447b --- /dev/null +++ b/openspec/changes/fix-enhanced-link-search-indexing/specs/enhanced-link-title-audit/spec.md @@ -0,0 +1,30 @@ +## ADDED Requirements + +### Requirement: All EnhancedLink usages in content pages have an explicit title prop +Every `<EnhancedLink>` component used in documentation content pages (i.e., pages under `docs/` that are not the contributing/enhanced-links.md documentation page) SHALL include a `title` prop with a human-readable name for the linked resource. + +#### Scenario: EnhancedLink with title is indexed by search +- **WHEN** a user searches for the title of a linked resource (e.g., "GitLab Style Guide") +- **THEN** the search results SHALL include the page containing the `<EnhancedLink>` for that resource + +#### Scenario: EnhancedLink without title is not present in content pages +- **WHEN** a content page under `docs/` (excluding `docs/contributing/enhanced-links.md`) contains a `<EnhancedLink>` component +- **THEN** the component SHALL have a non-empty `title` prop + +### Requirement: Titles are sourced from the metadata cache +When populating missing `title` props, the title value SHALL be derived from the `title` field in `docs/.vitepress/cache/link-metadata.json` for the corresponding URL. + +#### Scenario: Title matches cached metadata +- **WHEN** a `title` prop is added to an `<EnhancedLink>` for a URL that exists in the metadata cache +- **THEN** the title SHALL match the cached `metadata.title` value (or a human-readable shortened form of it, e.g., stripping ` | Site Name` suffixes) + +#### Scenario: URL not in cache falls back to hostname +- **WHEN** a `title` prop is added to an `<EnhancedLink>` for a URL that does NOT exist in the metadata cache +- **THEN** the title SHALL use the URL's hostname as a fallback (e.g., `"stylepedia.net"`) + +### Requirement: Contributing documentation examples are exempt +The `<EnhancedLink>` usages in `docs/contributing/enhanced-links.md` are intentional API examples and SHALL NOT be required to have a `title` prop. + +#### Scenario: Contributing page examples remain unchanged +- **WHEN** reviewing `docs/contributing/enhanced-links.md` +- **THEN** `<EnhancedLink>` usages without `title` props SHALL be left as-is to preserve their illustrative purpose diff --git a/openspec/changes/fix-enhanced-link-search-indexing/tasks.md b/openspec/changes/fix-enhanced-link-search-indexing/tasks.md new file mode 100644 index 0000000..1863957 --- /dev/null +++ b/openspec/changes/fix-enhanced-link-search-indexing/tasks.md @@ -0,0 +1,49 @@ +## 1. Audit EnhancedLink usages + +- [x] 1.1 Identify all `<EnhancedLink>` usages without a `title` prop in `docs/style-guides.md` +- [x] 1.2 Identify all `<EnhancedLink>` usages without a `title` prop in `docs/tools.md` +- [x] 1.3 Cross-reference each URL against `docs/.vitepress/cache/link-metadata.json` to get the canonical title + +## 2. Update docs/style-guides.md + +- [x] 2.1 Add `title` prop to `<EnhancedLink url="https://github.com/18F/guides" />` (Government & Standards section) +- [x] 2.2 Add `title` prop to `<EnhancedLink url="https://plainlanguage.gov/guidelines" />` (Government & Standards section) +- [x] 2.3 Add `title` prop to `<EnhancedLink url="https://www.un.org/dgacm/content/editorial-manual" />` (Government & Standards section) +- [x] 2.4 Add `title` prop to `<EnhancedLink url="https://developer.mozilla.org/en-US/docs/Web/Accessibility" />` (Web Standards & Accessibility section) +- [x] 2.5 Add `title` prop to `<EnhancedLink url="https://www.w3.org/TR/WCAG21/" />` (Web Standards & Accessibility section) +- [x] 2.6 Add `title` prop to `<EnhancedLink url="https://www.accessible-social.com/quick-guide" />` (Web Standards & Accessibility section) +- [x] 2.7 Add `title` prop to `<EnhancedLink url="https://developers.google.com/style/" />` (Developer-Focused section) +- [x] 2.8 Add `title` prop to `<EnhancedLink url="https://docs.microsoft.com/en-us/style-guide/welcome/" />` (Developer-Focused section) +- [x] 2.9 Add `title` prop to `<EnhancedLink url="https://redhat-documentation.github.io/" />` (Developer-Focused section) +- [x] 2.10 Add `title` prop to `<EnhancedLink url="https://stylepedia.net/" />` (Developer-Focused section) +- [x] 2.11 Add `title` prop to `<EnhancedLink url="https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines" />` (Cloud & Infrastructure section) +- [x] 2.12 Add `title` prop to `<EnhancedLink url="https://www.linode.com/docs/linode-writers-formatting-guide/" />` (Cloud & Infrastructure section) +- [x] 2.13 Add `title` prop to `<EnhancedLink url="https://github.com/rackerlabs/docs-style-guide/tree/master/style-guide" />` (Cloud & Infrastructure section) +- [x] 2.14 Add `title` prop to `<EnhancedLink url="https://developer.salesforce.com/docs/atlas.en-us.salesforce_pubs_style_guide.meta/salesforce_pubs_style_guide/overview.htm" />` (Cloud & Infrastructure section) +- [x] 2.15 Add `title` prop to `<EnhancedLink url="https://clig.dev/" />` (Technical Writing section) +- [x] 2.16 Add `title` prop to `<EnhancedLink url="https://github.com/lornajane/developer-style-guide" />` (Technical Writing section) +- [x] 2.17 Add `title` prop to `<EnhancedLink url="https://www.markdownguide.org/" />` (Technical Writing section) + +## 3. Update docs/tools.md + +- [x] 3.1 Add `title` prop to `<EnhancedLink url="https://nightwatchjs.org/" />` (Testing section) +- [x] 3.2 Add `title` prop to `<EnhancedLink url="https://playwright.dev/" />` (Testing section) +- [x] 3.3 Add `title` prop to `<EnhancedLink url="https://github.com/GoogleChrome/puppeteer" />` (Testing section) +- [x] 3.4 Add `title` prop to `<EnhancedLink url="https://www.selenium.dev/" />` (Testing section) +- [x] 3.5 Add `title` prop to `<EnhancedLink url="https://github.com/dequelabs/axe-cli" />` (Accessibility section) +- [x] 3.6 Add `title` prop to `<EnhancedLink url="https://webaim.org/resources/contrastchecker/" />` (Accessibility section) +- [x] 3.7 Add `title` prop to `<EnhancedLink url="https://support.siteimprove.com/hc/en-gb/articles/115000013031-Accessibility-Image-Alt-text-best-practices" />` (Accessibility section) +- [x] 3.8 Add `title` prop to `<EnhancedLink url="https://github.com/JakePartusch/lumberjack" />` (Accessibility section) +- [x] 3.9 Add `title` prop to `<EnhancedLink url="https://pa11y.org/" />` (Accessibility section) +- [x] 3.10 Add `title` prop to `<EnhancedLink url="https://www.doctave.com/" />` (Hosting section) +- [x] 3.11 Add `title` prop to `<EnhancedLink url="https://www.gitbook.com/" />` (Hosting section) +- [x] 3.12 Add `title` prop to `<EnhancedLink url="https://www.mintlify.com/" />` (Hosting section) +- [x] 3.13 Add `title` prop to `<EnhancedLink url="https://www.netlify.com/" />` (Hosting section) +- [x] 3.14 Add `title` prop to `<EnhancedLink url="https://readthedocs.org/" />` (Hosting section) + +## 4. Verify + +- [x] 4.1 Confirm no `<EnhancedLink>` without `title` remains in `docs/style-guides.md` (excluding contributing docs) +- [x] 4.2 Confirm no `<EnhancedLink>` without `title` remains in `docs/tools.md` +- [x] 4.3 Run a local VitePress build (`npm run docs:build`) and verify search returns results for "GitLab Style Guide", "Google Developer Documentation Style Guide", and "Playwright" +- [x] 4.4 Confirm `docs/contributing/enhanced-links.md` examples are unchanged