From 62c0fc6f0daafdeccf040eda09445ad33888c819 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 5 Sep 2025 15:48:34 -0400 Subject: [PATCH 1/2] Update AI instructions, tweak markdown linting - Clarify the MCP guide writer subagent's instructions - Only enforce prose wrap requirement for docs/ - Refactor markdownlint rule locations Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- .claude/agents/mcp-guide-writer.md | 100 +++++---------- .github/copilot-instructions.md | 139 ++++++++------------- .github/prompts/doc-review.prompt.md | 23 ++-- .markdownlint-cli2.jsonc | 8 +- .markdownlint.json | 8 +- .prettierrc | 13 +- AGENTS.md | 139 ++++++++------------- README.md | 12 +- docs/toolhive/.markdownlint.json | 10 ++ docs/toolhive/_partials/.markdownlint.json | 3 +- 10 files changed, 167 insertions(+), 288 deletions(-) create mode 100644 docs/toolhive/.markdownlint.json diff --git a/.claude/agents/mcp-guide-writer.md b/.claude/agents/mcp-guide-writer.md index 7a320410..60668d47 100644 --- a/.claude/agents/mcp-guide-writer.md +++ b/.claude/agents/mcp-guide-writer.md @@ -4,24 +4,18 @@ description: Use this agent when you need to create comprehensive usage guides f model: sonnet --- -You are an expert technical writer specializing in Model Context Protocol (MCP) -server documentation for ToolHive. Your role is to create comprehensive, -accurate, and user-friendly usage guides that help developers integrate and use -MCP servers effectively. +You are an expert technical writer specializing in Model Context Protocol (MCP) server documentation for ToolHive. Your role is to create comprehensive, accurate, and user-friendly usage guides that help developers integrate and use MCP servers effectively. + +When creating a guide, start by gathering comprehensive information about the MCP server, then structure the content to progressively guide users from basic setup to advanced usage scenarios. Focus on practical value and ensure every example is something users can actually implement. Your primary responsibilities: -1. **Research and Information Gathering**: Use the - `thv registry info ` command to gather detailed information - about the MCP server, including configuration options, capabilities, and - requirements. Use the `WebFetch` tool, the `fetch` MCP server, or `github` - MCP server to retrieve additional documentation from the server's repository. - -2. **Create Structured MDX Documentation**: Write guides as MDX files in - `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. - Each guide must include ONLY these sections: - - Front matter with title, description, last_update author and today's date - (`YYYY-MM-DD` format) +1. **Research and Information Gathering**: + - Use the `thv registry info --format json` command to gather detailed information about the MCP server, including configuration options, capabilities, and requirements. + - Use the `WebFetch` tool, the `fetch` MCP server, or `github` MCP server to retrieve additional documentation from the server's repository. + +2. **Create Structured MDX Documentation**: Write guides as MDX files in `docs/toolhive/guides-mcp/` following the `_template.mdx` structure exactly. Each guide must include ONLY these sections: + - Front matter with title, description, last_update author and today's date (`YYYY-MM-DD` format) - Overview section explaining what the MCP server does - Metadata section with `` component - Usage section with tabbed UI/CLI/Kubernetes instructions @@ -32,38 +26,29 @@ Your primary responsibilities: - Available tools/capabilities section (handled by MCPMetadata component) - Configuration options section (handled by MCPMetadata component) -3. **Ensure Technical Accuracy**: All configuration examples must be valid and - tested. Reference the existing ToolHive documentation in the `docs/toolhive/` - directory as the source of truth for: - - Available `thv` CLI commands and their syntax (reference: - `docs/toolhive/reference/cli/*.md` or run `thv --help`) - - Kubernetes CRD specifications and fields (reference: - `static/api-specs/toolhive-crd-api.md`) - - UI configuration options and workflows - -4. **Follow Documentation Standards**: Adhere to the project's writing style - guide (`STYLE_GUIDE.md`) including: +3. **Ensure Technical Accuracy**: All configuration examples must be valid and tested. Reference the existing ToolHive documentation in the `docs/toolhive/` directory as the source of truth for: + - Available `thv` CLI commands and their syntax (reference: `docs/toolhive/reference/cli/*.md` or run `thv --help`) + - Kubernetes CRD specifications and fields (reference: `static/api-specs/toolhive-crd-api.md`) + - UI configuration options and workflows (reference: `docs/toolhive/guides-ui/*`) + +4. **Follow Documentation Standards**: Adhere to the project's writing style guide (`STYLE_GUIDE.md`) including: - Use US English with casual, conversational tone - Address readers in second person ("you", "your") - Use sentence case for headings - - Apply proper Markdown formatting (ATX headings, fenced code blocks with - language tags) + - Apply proper Markdown formatting (ATX headings, fenced code blocks with language tags) - Include descriptive alt text for images - - Use admonitions (:::note, :::tip, :::warning) for important information, - with :::tip[Title] format for custom titles + - Use admonitions (`:::note`, `:::tip`, `:::warning`) for important information, using `:::tip[Title]` format for custom titles -5. **Create Practical Examples**: Provide real-world, actionable examples that - users can copy and modify. Include: +5. **Create Practical Examples**: Provide real-world, actionable examples that users can copy and modify. Include: - Multiple CLI usage examples from basic to advanced scenarios - Complete Kubernetes manifests with proper YAML formatting - UI configuration guidance focusing on unique features - Sample prompts that demonstrate real use cases for the MCP server - Security-focused examples using network isolation and permission profiles -6. **Reference Existing Guides**: Use `docs/toolhive/guides-mcp/_template.mdx` - and `docs/toolhive/guides-mcp/github.mdx` as references for exact structure, - tone, and depth of coverage. Follow the template structure precisely without - adding additional sections. +6. **Reference Existing Guides**: + - Use `docs/toolhive/guides-mcp/_template.mdx` as references for exact structure, + - Use existing guides as reference for tone and depth of coverage. A good example is `docs/toolhive/guides-mcp/github.mdx` 7. **Quality Assurance**: Before finalizing, verify that: - All code examples are syntactically correct @@ -74,38 +59,15 @@ Your primary responsibilities: **Key Requirements for Content Structure:** -1. **Overview Section**: Provide a clear, concise explanation of the MCP - server's purpose and key features. Include links to official documentation - and highlight what makes this server unique. +1. **Overview Section**: Provide a clear, concise explanation of the MCP server's purpose and key features. Include links to official documentation and highlight what makes this server unique. 2. **Usage Section Tabs**: - - **UI Tab**: Focus on unique configuration options and features, not basic - registry selection. The ToolHive UI includes a configuration interface that - allows users to set the secrets and environment variables defined in the - server metadata, customize command-line arguments, and add volume mounts. - Provide step-by-step instructions for these configurations if needed for - the MCP server. - - **CLI Tab**: Provide multiple progressive examples from basic to advanced - usage, including security configurations. - - **Kubernetes Tab**: Include complete, working YAML manifests with proper - formatting and comments. - -3. **Sample Prompts**: Create 3-6 realistic prompts that demonstrate the - server's capabilities. Make them specific and actionable, not generic. - -4. **Recommended Practices**: Focus on security, performance, and reliability - best practices specific to the MCP server. - -**Critical Guidelines:** - -- Never add tools/capabilities sections (MCPMetadata handles this) -- Always include the MCPMetadata component exactly as shown: - `` -- Ensure all examples are copy-pasteable and functional -- Use proper YAML formatting with `title=` attributes for code blocks -- Include security considerations like network isolation where relevant - -When creating a guide, start by gathering comprehensive information about the -MCP server, then structure the content to progressively guide users from basic -setup to advanced usage scenarios. Focus on practical value and ensure every -example is something users can actually implement. + + Using the MCP server's documentation as reference, use its unique features and use cases to create detailed instructions for each tab: + - **UI Tab**: Focus on unique configuration options and features, not basic registry selection. The ToolHive UI includes a configuration interface that allows users to set the secrets and environment variables defined in the server metadata, customize command-line arguments, and add volume mounts. Provide step-by-step instructions for these configurations if needed for the MCP server. + - **CLI Tab**: Provide multiple progressive examples from basic to advanced usage, including security configurations. + - **Kubernetes Tab**: Include complete, working YAML manifests with proper formatting and comments. + +3. **Sample Prompts**: Create 3-6 realistic prompts that demonstrate the server's capabilities. Make them specific and actionable, not generic. + +4. **Recommended Practices**: Focus on security, performance, and reliability best practices specific to the MCP server. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 5295ec98..d5f664c6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,26 +1,18 @@ # Project overview -This is the user-facing documentation for ToolHive, an open source tool that -helps you run and manage Model Context Protocol (MCP) servers easily and -securely. The site is built using Docusaurus and deployed with Vercel. +This is the user-facing documentation for ToolHive, an open source tool that helps you run and manage Model Context Protocol (MCP) servers easily and securely. The site is built using Docusaurus and deployed with Vercel. ## Folder structure -- `/docs`: contains the main documentation files. Each file corresponds to a - page in the documentation. -- `/static`: contains static assets like images, icons, and other files that are - served directly. -- `/src`: contains the source code for the website, including components, - styles, and customizations. +- `/docs`: contains the main documentation files. Each file corresponds to a page in the documentation. +- `/static`: contains static assets like images, icons, and other files that are served directly. +- `/src`: contains the source code for the website, including components, styles, and customizations. ## Primary configuration files -- `/docusaurus.config.ts`: the main configuration file for Docusaurus, where you - define site metadata, theme, plugins, and other settings. -- `/sidebars.ts`: defines the structure of the documentation sidebar, including - which pages appear in the sidebar and their order. -- `/vercel.json`: configuration file for Vercel deployment, specifying build - settings and redirects. +- `/docusaurus.config.ts`: the main configuration file for Docusaurus, where you define site metadata, theme, plugins, and other settings. +- `/sidebars.ts`: defines the structure of the documentation sidebar, including which pages appear in the sidebar and their order. +- `/vercel.json`: configuration file for Vercel deployment, specifying build settings and redirects. ## Libraries and tools @@ -31,28 +23,27 @@ securely. The site is built using Docusaurus and deployed with Vercel. Code quality tools: -- Prettier for code formatting - `npm run prettier` to check, - `npm run prettier:fix` to auto-fix. -- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` - to check, `npm run markdownlint:fix` to auto-fix. -- ESLint for JavaScript/TypeScript linting - `npm run eslint` to check, - `npm run eslint:fix` to auto-fix. +- Prettier for code formatting - `npm run prettier` to check, `npm run prettier:fix` to auto-fix. +- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` to check, `npm run markdownlint:fix` to auto-fix. +- ESLint for JavaScript/TypeScript linting - `npm run eslint` to check, `npm run eslint:fix` to auto-fix. ## Audience -The primary audience is developers and DevOps professionals who want to run and -manage Model Context Protocol (MCP) servers using ToolHive. They may be new to -MCP servers or have some experience with them. +The primary audience is developers and DevOps professionals who want to run and manage Model Context Protocol (MCP) servers using ToolHive. They may be new to MCP servers or have some experience with them. -The documentation should be accessible to a wide range of technical users, -including those who may not be familiar with the specific technologies used in -ToolHive. +The documentation should be accessible to a wide range of technical users, including those who may not be familiar with the specific technologies used in ToolHive. + +## Review process + +When you are asked to review documentation changes, you are a subject matterexpert (SME) for the content and a technical writer. Your role is to ensure that the content is accurate, clear, and consistent with the project's goals and standards. + +- Prioritize clarity, accuracy, and consistency. +- Ensure that the content is easy to understand, follows the writing style guide. +- Do not consider markdown formatting or syntax, as these will be handled by the code quality tools. ## Writing style guide -The primary goal of the documentation is to be clear, concise, and -user-friendly. The writing style should be approachable and easy to understand, -while still providing the necessary technical details. +The primary goal of the documentation is to be clear, concise, and user-friendly. The writing style should be approachable and easy to understand, while still providing the necessary technical details. The project's official language is US English. @@ -61,48 +52,36 @@ The project's official language is US English. - Strive for a casual and conversational tone without becoming overly informal. - Be friendly and relatable while retaining credibility and professionalism. - Avoid slang and colloquial expressions. -- Use clear, straightforward language and avoid overly complex jargon to make - content accessible to a wide audience. +- Use clear, straightforward language and avoid overly complex jargon to make content accessible to a wide audience. - Use active voice instead of passive voice. -- Address the reader using the second person ("you", "your"). Avoid the first - person ("we", "our") and third person ("the user", "a developer"). +- Address the reader using the second person ("you", "your"). Avoid the first person ("we", "our") and third person ("the user", "a developer"). ### Capitalization -- Capitalize proper nouns like names, companies, and products. Generally, don't - capitalize features or generic terms. +- Capitalize proper nouns like names, companies, and products. Generally, don't capitalize features or generic terms. - Use sentence case in titles and headings. -- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is - expected to change a value. +- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is expected to change a value. - Expand acronyms on first use, then use the acronym in subsequent references. - - Exception: MCP is used ubiquitously in this project, so it does not need to - be expanded on first use. + - Exception: MCP is used ubiquitously in this project, so it does not need to be expanded on first use. ### Punctuation - Use the Oxford comma (aka serial commas) when listing items in a series. - Use one space between sentences. -- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and - curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). +- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). ### Links -- Use descriptive link text. Besides providing clear context to the reader, this - improves accessibility for screen readers. -- When referencing other docs/headings by title, use sentence case so the - reference matches the corresponding title or heading. +- Use descriptive link text. Besides providing clear context to the reader, this improves accessibility for screen readers. +- When referencing other docs/headings by title, use sentence case so the reference matches the corresponding title or heading. ### Images - Use images sparingly and only when they add value to the content. -- Use images to illustrate complex concepts, provide examples, or enhance - understanding. -- Use screenshots to show UI elements or workflows, but ensure they are clear, - relevant, and add value to the content. -- Don't use images of text, code samples, or terminal output. Use actual text so - readers can copy/paste and find the contents via search engines. -- Add alt text to images to describe their content and purpose. This improves - accessibility for users with visual impairments. +- Use images to illustrate complex concepts, provide examples, or enhance understanding. +- Use screenshots to show UI elements or workflows, but ensure they are clear, relevant, and add value to the content. +- Don't use images of text, code samples, or terminal output. Use actual text so readers can copy/paste and find the contents via search engines. +- Add alt text to images to describe their content and purpose. This improves accessibility for users with visual impairments. ### Examples @@ -112,19 +91,16 @@ The project's official language is US English. ### Formatting - Bold: use when referring to UI elements; prefer bold over quotes. -- Italics: emphasize particular words or phrases, such as when - introducing/defining a term. +- Italics: emphasize particular words or phrases, such as when introducing/defining a term. - Underscore: do not use; reserved for links. -- Use inline code formatting for short code elements, such as variable names, - function names, or command-line options. +- Use inline code formatting for short code elements, such as variable names, function names, or command-line options. - Use block code formatting for longer code snippets or examples. ### Word list Common terms used in this project: -- ToolHive - this project, an open source tool that helps you run and manage MCP - servers easily and securely +- ToolHive - this project, an open source tool that helps you run and manage MCP servers easily and securely - Stacklok - the company behind ToolHive - GitHub Copilot - Model Context Protocol (MCP) @@ -132,14 +108,11 @@ Common terms used in this project: - large language model (LLM) - Visual Studio Code ("VS Code" after first use) -Check this list for consistent use within the documentation. If you find -inconsistencies, update the text to match the preferred term. If you find a term -that is not listed here, consider adding it to the list for future reference. +Check this list for consistent use within the documentation. If you find inconsistencies, update the text to match the preferred term. If you find a term that is not listed here, consider adding it to the list for future reference. ## Markdown style -Prettier and markdownlint are used to enforce the following Markdown style -conventions. +Prettier and markdownlint are used to enforce the following Markdown style conventions. - Headings: use "ATX-style" headings - Use unique headings within a document @@ -147,37 +120,23 @@ conventions. - Bold: Use the `**` syntax for bold text, not `__` - Italics: Use the `__` syntax for italic text, not `*` - Ordered lists: use lazy numbering for long or verbose lists. - - Note: this is a "soft" recommendation. It is also intended only for Markdown - documents that are read through a rendering engine. If the Markdown will be - consumed in raw form like a repo README file, use real numbering. -- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare - the language. If the language is unknown or plain text like log output, use - `text` as the language. + - Note: this is a "soft" recommendation. It is also intended only for Markdown documents that are read through a rendering engine. If the Markdown will be consumed in raw form like a repo README file, use real numbering. +- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare the language. If the language is unknown or plain text like log output, use `text` as the language. - Add blank lines around headings, lists, and code blocks. - No trailing whitespace on lines. - - Use the `\` character at the end of a line for a single-line break, not the - two-space syntax which is easy to miss. Exception: -- Line limit: wrap lines at 80 characters; exceptions for links, tables, - headings, and code blocks + - Use the `\` character at the end of a line for a single-line break, not the two-space syntax which is easy to miss. Exception: +- Line limit: wrap lines at 80 characters; exceptions for links, tables, headings, and code blocks ### Docusaurus specifics -This website is built using Docusaurus, which has some specific requirements and -conventions for Markdown files: +This website is built using Docusaurus, which has some specific requirements and conventions for Markdown files: -- Heading 1 is reserved for the page title, typically defined in the Markdown - front matter section. Sections within a page begin with Heading 2 (`##`). -- Use relative file links (with .md/.mdx extensions) when referring to other - pages. +- Heading 1 is reserved for the page title, typically defined in the Markdown front matter section. Sections within a page begin with Heading 2 (`##`). +- Use relative file links (with .md/.mdx extensions) when referring to other pages. - Use the .mdx extension for pages containing JSX includes. -- Use the front matter section on all pages. At a minimum, set the `title` (this - is rendered into the page as an H1) and a short `description`. -- Use the `admonition` component for notes, tips, warnings, and other - annotations. This provides a consistent look and feel across the site. - - Use the `:::type` syntax to define the admonition type, such as `note`, - `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, - e.g. `:::info[Title]`. Add empty lines around the start and end directives. +- Use the front matter section on all pages. At a minimum, set the `title` (this is rendered into the page as an H1) and a short `description`. +- Use the `admonition` component for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site. + - Use the `:::type` syntax to define the admonition type, such as `note`, `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, e.g. `:::info[Title]`. Add empty lines around the start and end directives. - Place images in `static/img` using WebP, PNG, or SVG format. -- Use the `ThemedImage` component to provide both light and dark mode - screenshots for apps/UIs that support both. +- Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. - Use the `Tabs` and `TabItem` components to create tabbed content sections. diff --git a/.github/prompts/doc-review.prompt.md b/.github/prompts/doc-review.prompt.md index e1a66452..68f2b153 100644 --- a/.github/prompts/doc-review.prompt.md +++ b/.github/prompts/doc-review.prompt.md @@ -6,29 +6,20 @@ description: 'Perform a documentation clarity and style review' Perform a review of the documentation provided in the context. -If explicit content is not provided, perform a review of all changes between the -current branch and the `main` branch, including committed and unstaged changes. -Use a PR-style approach: review all changed files, including documentation and -code, and provide actionable feedback. +If explicit content is not provided, perform a review of all changes between the current branch and the `main` branch, including committed and unstaged changes. Use a PR-style approach: review all changed files, including documentation and code, and provide actionable feedback. **Review instructions:** -- Focus on clarity, conciseness, technical accuracy, and adherence to the - writing style guide. -- For documentation, check tone, accessibility, and user-friendliness for - developers and DevOps professionals. -- For code, check correctness, readability, maintainability, and adherence to - project conventions. +- Focus on clarity, conciseness, technical accuracy, and adherence to the writing style guide. +- For documentation, check tone, accessibility, and user-friendliness for developers and DevOps professionals. +- For code, check correctness, readability, maintainability, and adherence to project conventions. - Use inline comments or suggestions for specific lines or sections. - Summarize major issues and list minor suggestions. -- Indicate whether you would "approve", "request changes", or "comment" as in a - typical PR review. +- Indicate whether you would "approve", "request changes", or "comment" as in a typical PR review. -Refer to the writing style guide: -[copilot-instructions.md](../copilot-instructions.md) +Refer to the writing style guide: [STYLE-GUIDE.md](../../STYLE-GUIDE.md) -You can run `editFiles` to make changes based on your review. You can also run -`runCommands` to test the site or check for errors: +You can run `editFiles` to make changes based on your review. You can also run `runCommands` to test the site or check for errors: - `npm run build` to build the documentation site. - `npm run start` to start the local development server. diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index c0b19493..b2033ea4 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,11 +1,5 @@ { "gitignore": true, "globs": ["**/*.md"], - "ignores": [ - "docs/toolhive/reference/cli/", - "static/api-specs/*.md", - ".github/pull_request_template.md", - ".github/prompts/*.md", - ".claude/**/*.md", - ], + "ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"], } diff --git a/.markdownlint.json b/.markdownlint.json index 6b6876d4..7ecb7743 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,4 +1,5 @@ { + "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.35.0/schema/.markdownlint.jsonc", "code-block-style": { "style": "fenced" }, @@ -8,17 +9,14 @@ "emphasis-style": { "style": "underscore" }, + "first-line-h1": false, "heading-style": { "style": "atx" }, "hr-style": { "style": "---" }, - "line-length": { - "code_blocks": false, - "line_length": 80, - "tables": false - }, + "line-length": false, "no-bare-urls": false, "no-inline-html": { "allowed_elements": ["details", "summary"] diff --git a/.prettierrc b/.prettierrc index 3a1c0178..e806d12b 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,9 +1,18 @@ { "jsxSingleQuote": true, "printWidth": 80, - "proseWrap": "always", + "proseWrap": "preserve", "singleQuote": true, "tabWidth": 2, "trailingComma": "es5", - "useTabs": false + "useTabs": false, + + "overrides": [ + { + "files": ["docs/**/*.md", "docs/**/*.mdx"], + "options": { + "proseWrap": "always" + } + } + ] } diff --git a/AGENTS.md b/AGENTS.md index 5295ec98..d5f664c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,18 @@ # Project overview -This is the user-facing documentation for ToolHive, an open source tool that -helps you run and manage Model Context Protocol (MCP) servers easily and -securely. The site is built using Docusaurus and deployed with Vercel. +This is the user-facing documentation for ToolHive, an open source tool that helps you run and manage Model Context Protocol (MCP) servers easily and securely. The site is built using Docusaurus and deployed with Vercel. ## Folder structure -- `/docs`: contains the main documentation files. Each file corresponds to a - page in the documentation. -- `/static`: contains static assets like images, icons, and other files that are - served directly. -- `/src`: contains the source code for the website, including components, - styles, and customizations. +- `/docs`: contains the main documentation files. Each file corresponds to a page in the documentation. +- `/static`: contains static assets like images, icons, and other files that are served directly. +- `/src`: contains the source code for the website, including components, styles, and customizations. ## Primary configuration files -- `/docusaurus.config.ts`: the main configuration file for Docusaurus, where you - define site metadata, theme, plugins, and other settings. -- `/sidebars.ts`: defines the structure of the documentation sidebar, including - which pages appear in the sidebar and their order. -- `/vercel.json`: configuration file for Vercel deployment, specifying build - settings and redirects. +- `/docusaurus.config.ts`: the main configuration file for Docusaurus, where you define site metadata, theme, plugins, and other settings. +- `/sidebars.ts`: defines the structure of the documentation sidebar, including which pages appear in the sidebar and their order. +- `/vercel.json`: configuration file for Vercel deployment, specifying build settings and redirects. ## Libraries and tools @@ -31,28 +23,27 @@ securely. The site is built using Docusaurus and deployed with Vercel. Code quality tools: -- Prettier for code formatting - `npm run prettier` to check, - `npm run prettier:fix` to auto-fix. -- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` - to check, `npm run markdownlint:fix` to auto-fix. -- ESLint for JavaScript/TypeScript linting - `npm run eslint` to check, - `npm run eslint:fix` to auto-fix. +- Prettier for code formatting - `npm run prettier` to check, `npm run prettier:fix` to auto-fix. +- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` to check, `npm run markdownlint:fix` to auto-fix. +- ESLint for JavaScript/TypeScript linting - `npm run eslint` to check, `npm run eslint:fix` to auto-fix. ## Audience -The primary audience is developers and DevOps professionals who want to run and -manage Model Context Protocol (MCP) servers using ToolHive. They may be new to -MCP servers or have some experience with them. +The primary audience is developers and DevOps professionals who want to run and manage Model Context Protocol (MCP) servers using ToolHive. They may be new to MCP servers or have some experience with them. -The documentation should be accessible to a wide range of technical users, -including those who may not be familiar with the specific technologies used in -ToolHive. +The documentation should be accessible to a wide range of technical users, including those who may not be familiar with the specific technologies used in ToolHive. + +## Review process + +When you are asked to review documentation changes, you are a subject matterexpert (SME) for the content and a technical writer. Your role is to ensure that the content is accurate, clear, and consistent with the project's goals and standards. + +- Prioritize clarity, accuracy, and consistency. +- Ensure that the content is easy to understand, follows the writing style guide. +- Do not consider markdown formatting or syntax, as these will be handled by the code quality tools. ## Writing style guide -The primary goal of the documentation is to be clear, concise, and -user-friendly. The writing style should be approachable and easy to understand, -while still providing the necessary technical details. +The primary goal of the documentation is to be clear, concise, and user-friendly. The writing style should be approachable and easy to understand, while still providing the necessary technical details. The project's official language is US English. @@ -61,48 +52,36 @@ The project's official language is US English. - Strive for a casual and conversational tone without becoming overly informal. - Be friendly and relatable while retaining credibility and professionalism. - Avoid slang and colloquial expressions. -- Use clear, straightforward language and avoid overly complex jargon to make - content accessible to a wide audience. +- Use clear, straightforward language and avoid overly complex jargon to make content accessible to a wide audience. - Use active voice instead of passive voice. -- Address the reader using the second person ("you", "your"). Avoid the first - person ("we", "our") and third person ("the user", "a developer"). +- Address the reader using the second person ("you", "your"). Avoid the first person ("we", "our") and third person ("the user", "a developer"). ### Capitalization -- Capitalize proper nouns like names, companies, and products. Generally, don't - capitalize features or generic terms. +- Capitalize proper nouns like names, companies, and products. Generally, don't capitalize features or generic terms. - Use sentence case in titles and headings. -- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is - expected to change a value. +- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is expected to change a value. - Expand acronyms on first use, then use the acronym in subsequent references. - - Exception: MCP is used ubiquitously in this project, so it does not need to - be expanded on first use. + - Exception: MCP is used ubiquitously in this project, so it does not need to be expanded on first use. ### Punctuation - Use the Oxford comma (aka serial commas) when listing items in a series. - Use one space between sentences. -- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and - curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). +- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). ### Links -- Use descriptive link text. Besides providing clear context to the reader, this - improves accessibility for screen readers. -- When referencing other docs/headings by title, use sentence case so the - reference matches the corresponding title or heading. +- Use descriptive link text. Besides providing clear context to the reader, this improves accessibility for screen readers. +- When referencing other docs/headings by title, use sentence case so the reference matches the corresponding title or heading. ### Images - Use images sparingly and only when they add value to the content. -- Use images to illustrate complex concepts, provide examples, or enhance - understanding. -- Use screenshots to show UI elements or workflows, but ensure they are clear, - relevant, and add value to the content. -- Don't use images of text, code samples, or terminal output. Use actual text so - readers can copy/paste and find the contents via search engines. -- Add alt text to images to describe their content and purpose. This improves - accessibility for users with visual impairments. +- Use images to illustrate complex concepts, provide examples, or enhance understanding. +- Use screenshots to show UI elements or workflows, but ensure they are clear, relevant, and add value to the content. +- Don't use images of text, code samples, or terminal output. Use actual text so readers can copy/paste and find the contents via search engines. +- Add alt text to images to describe their content and purpose. This improves accessibility for users with visual impairments. ### Examples @@ -112,19 +91,16 @@ The project's official language is US English. ### Formatting - Bold: use when referring to UI elements; prefer bold over quotes. -- Italics: emphasize particular words or phrases, such as when - introducing/defining a term. +- Italics: emphasize particular words or phrases, such as when introducing/defining a term. - Underscore: do not use; reserved for links. -- Use inline code formatting for short code elements, such as variable names, - function names, or command-line options. +- Use inline code formatting for short code elements, such as variable names, function names, or command-line options. - Use block code formatting for longer code snippets or examples. ### Word list Common terms used in this project: -- ToolHive - this project, an open source tool that helps you run and manage MCP - servers easily and securely +- ToolHive - this project, an open source tool that helps you run and manage MCP servers easily and securely - Stacklok - the company behind ToolHive - GitHub Copilot - Model Context Protocol (MCP) @@ -132,14 +108,11 @@ Common terms used in this project: - large language model (LLM) - Visual Studio Code ("VS Code" after first use) -Check this list for consistent use within the documentation. If you find -inconsistencies, update the text to match the preferred term. If you find a term -that is not listed here, consider adding it to the list for future reference. +Check this list for consistent use within the documentation. If you find inconsistencies, update the text to match the preferred term. If you find a term that is not listed here, consider adding it to the list for future reference. ## Markdown style -Prettier and markdownlint are used to enforce the following Markdown style -conventions. +Prettier and markdownlint are used to enforce the following Markdown style conventions. - Headings: use "ATX-style" headings - Use unique headings within a document @@ -147,37 +120,23 @@ conventions. - Bold: Use the `**` syntax for bold text, not `__` - Italics: Use the `__` syntax for italic text, not `*` - Ordered lists: use lazy numbering for long or verbose lists. - - Note: this is a "soft" recommendation. It is also intended only for Markdown - documents that are read through a rendering engine. If the Markdown will be - consumed in raw form like a repo README file, use real numbering. -- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare - the language. If the language is unknown or plain text like log output, use - `text` as the language. + - Note: this is a "soft" recommendation. It is also intended only for Markdown documents that are read through a rendering engine. If the Markdown will be consumed in raw form like a repo README file, use real numbering. +- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare the language. If the language is unknown or plain text like log output, use `text` as the language. - Add blank lines around headings, lists, and code blocks. - No trailing whitespace on lines. - - Use the `\` character at the end of a line for a single-line break, not the - two-space syntax which is easy to miss. Exception: -- Line limit: wrap lines at 80 characters; exceptions for links, tables, - headings, and code blocks + - Use the `\` character at the end of a line for a single-line break, not the two-space syntax which is easy to miss. Exception: +- Line limit: wrap lines at 80 characters; exceptions for links, tables, headings, and code blocks ### Docusaurus specifics -This website is built using Docusaurus, which has some specific requirements and -conventions for Markdown files: +This website is built using Docusaurus, which has some specific requirements and conventions for Markdown files: -- Heading 1 is reserved for the page title, typically defined in the Markdown - front matter section. Sections within a page begin with Heading 2 (`##`). -- Use relative file links (with .md/.mdx extensions) when referring to other - pages. +- Heading 1 is reserved for the page title, typically defined in the Markdown front matter section. Sections within a page begin with Heading 2 (`##`). +- Use relative file links (with .md/.mdx extensions) when referring to other pages. - Use the .mdx extension for pages containing JSX includes. -- Use the front matter section on all pages. At a minimum, set the `title` (this - is rendered into the page as an H1) and a short `description`. -- Use the `admonition` component for notes, tips, warnings, and other - annotations. This provides a consistent look and feel across the site. - - Use the `:::type` syntax to define the admonition type, such as `note`, - `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, - e.g. `:::info[Title]`. Add empty lines around the start and end directives. +- Use the front matter section on all pages. At a minimum, set the `title` (this is rendered into the page as an H1) and a short `description`. +- Use the `admonition` component for notes, tips, warnings, and other annotations. This provides a consistent look and feel across the site. + - Use the `:::type` syntax to define the admonition type, such as `note`, `tip`, `info`, `warning`, or `danger`. Use square brackets to add a title, e.g. `:::info[Title]`. Add empty lines around the start and end directives. - Place images in `static/img` using WebP, PNG, or SVG format. -- Use the `ThemedImage` component to provide both light and dark mode - screenshots for apps/UIs that support both. +- Use the `ThemedImage` component to provide both light and dark mode screenshots for apps/UIs that support both. - Use the `Tabs` and `TabItem` components to create tabbed content sections. diff --git a/README.md b/README.md index 69c68c02..9ee98cba 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,7 @@ at [https://docs.stacklok.com](https://docs.stacklok.com). ## Contributing to docs -We welcome contributions to the Stacklok documentation - if you find something -missing, wrong, or unclear, please let us know via an issue or open a PR! +We welcome contributions to the Stacklok documentation - if you find something missing, wrong, or unclear, please let us know via an issue or open a PR! Please review the [style guide](./STYLE-GUIDE.md) for help with voice, tone, and formatting. @@ -83,10 +82,7 @@ This site is built with [Docusaurus](https://docusaurus.io/). -[deployment-img]: - https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&label=Vercel%20deployment +[deployment-img]: https://img.shields.io/github/deployments/stacklok/docs-website/Production?logo=vercel&label=Vercel%20deployment [deployment]: https://github.com/stacklok/docs-website/deployments/Production -[devcontainer-img]: - https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue -[devcontainer]: - https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website +[devcontainer-img]: https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue +[devcontainer]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/stacklok/docs-website diff --git a/docs/toolhive/.markdownlint.json b/docs/toolhive/.markdownlint.json new file mode 100644 index 00000000..de0fedc0 --- /dev/null +++ b/docs/toolhive/.markdownlint.json @@ -0,0 +1,10 @@ +{ + "extends": "../../.markdownlint.json", + + "first-line-h1": true, + "line-length": { + "code_blocks": false, + "line_length": 80, + "tables": false + } +} diff --git a/docs/toolhive/_partials/.markdownlint.json b/docs/toolhive/_partials/.markdownlint.json index 8421633d..3e2b9516 100644 --- a/docs/toolhive/_partials/.markdownlint.json +++ b/docs/toolhive/_partials/.markdownlint.json @@ -1,4 +1,5 @@ { - "extends": "../../../.markdownlint.json", + "extends": "../.markdownlint.json", + "first-line-h1": false } From 4128a762747dc94772cb42c5136ddc0e5d350bf0 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 5 Sep 2025 15:50:20 -0400 Subject: [PATCH 2/2] Fix typo Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d5f664c6..f619dc40 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ The documentation should be accessible to a wide range of technical users, inclu ## Review process -When you are asked to review documentation changes, you are a subject matterexpert (SME) for the content and a technical writer. Your role is to ensure that the content is accurate, clear, and consistent with the project's goals and standards. +When you are asked to review documentation changes, you are a subject matter expert (SME) for the content and a technical writer. Your role is to ensure that the content is accurate, clear, and consistent with the project's goals and standards. - Prioritize clarity, accuracy, and consistency. - Ensure that the content is easy to understand, follows the writing style guide.