|
| 1 | +# Project overview |
| 2 | + |
| 3 | +This is the user-facing documentation for ToolHive, an open source tool that |
| 4 | +helps you run and manage Model Context Protocol (MCP) servers easily and |
| 5 | +securely. The site is built using Docusaurus and deployed with Vercel. |
| 6 | + |
| 7 | +## Folder structure |
| 8 | + |
| 9 | +- `/docs`: contains the main documentation files. Each file corresponds to a |
| 10 | + page in the documentation. |
| 11 | +- `/static`: contains static assets like images, icons, and other files that are |
| 12 | + served directly. |
| 13 | +- `/src`: contains the source code for the website, including components, |
| 14 | + styles, and customizations. |
| 15 | + |
| 16 | +## Primary configuration files |
| 17 | + |
| 18 | +- `/docusaurus.config.ts`: the main configuration file for Docusaurus, where you |
| 19 | + define site metadata, theme, plugins, and other settings. |
| 20 | +- `/sidebars.ts`: defines the structure of the documentation sidebar, including |
| 21 | + which pages appear in the sidebar and their order. |
| 22 | +- `/vercel.json`: configuration file for Vercel deployment, specifying build |
| 23 | + settings and redirects. |
| 24 | + |
| 25 | +## Libraries and tools |
| 26 | + |
| 27 | +- Docusaurus for the documentation site framework. |
| 28 | +- React and TypeScript for building custom components and pages. |
| 29 | +- npm for package management. |
| 30 | +- Vercel for deployment and hosting. |
| 31 | + |
| 32 | +Code quality tools: |
| 33 | + |
| 34 | +- Prettier for code formatting. |
| 35 | +- markdownlint for enforcing Markdown style conventions. |
| 36 | +- ESLint for JavaScript/TypeScript linting. |
| 37 | + |
| 38 | +## Audience |
| 39 | + |
| 40 | +The primary audience is developers and DevOps professionals who want to run and |
| 41 | +manage Model Context Protocol (MCP) servers using ToolHive. They may be new to |
| 42 | +MCP servers or have some experience with them. |
| 43 | + |
| 44 | +The documentation should be accessible to a wide range of technical users, |
| 45 | +including those who may not be familiar with the specific technologies used in |
| 46 | +ToolHive. |
| 47 | + |
| 48 | +## Writing style guide |
| 49 | + |
| 50 | +The primary goal of the documentation is to be clear, concise, and |
| 51 | +user-friendly. The writing style should be approachable and easy to understand, |
| 52 | +while still providing the necessary technical details. |
| 53 | + |
| 54 | +The project's official language is US English. |
| 55 | + |
| 56 | +### Tone and voice |
| 57 | + |
| 58 | +- Strive for a casual and conversational tone without becoming overly informal. |
| 59 | +- Be friendly and relatable while retaining credibility and professionalism. |
| 60 | +- Avoid slang and colloquial expressions. |
| 61 | +- Use clear, straightforward language and avoid overly complex jargon to make |
| 62 | + content accessible to a wide audience. |
| 63 | +- Use active voice instead of passive voice. |
| 64 | +- Address the reader using the second person ("you", "your"). Avoid the first |
| 65 | + person ("we", "our") and third person ("the user", "a developer"). |
| 66 | + |
| 67 | +### Capitalization |
| 68 | + |
| 69 | +- Capitalize proper nouns like names, companies, and products. Generally, don't |
| 70 | + capitalize features or generic terms. |
| 71 | +- Use sentence case in titles and headings. |
| 72 | +- Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is |
| 73 | + expected to change a value. |
| 74 | +- Expand acronyms on first use, then use the acronym in subsequent references. |
| 75 | + - Exception: MCP is used ubiquitously in this project, so it does not need to |
| 76 | + be expanded on first use. |
| 77 | + |
| 78 | +### Punctuation |
| 79 | + |
| 80 | +- Use the Oxford comma (aka serial commas) when listing items in a series. |
| 81 | +- Use one space between sentences. |
| 82 | +- Use straight double quotes and apostrophes. Replace smart quotes (“ ”) and |
| 83 | + curly apostrophes (’ ’) with straight quotes (") and straight apostrophes ('). |
| 84 | + |
| 85 | +### Links |
| 86 | + |
| 87 | +- Use descriptive link text. Besides providing clear context to the reader, this |
| 88 | + improves accessibility for screen readers. |
| 89 | +- When referencing other docs/headings by title, use sentence case so the |
| 90 | + reference matches the corresponding title or heading. |
| 91 | + |
| 92 | +### Images |
| 93 | + |
| 94 | +- Use images sparingly and only when they add value to the content. |
| 95 | +- Use images to illustrate complex concepts, provide examples, or enhance |
| 96 | + understanding. |
| 97 | +- Use screenshots to show UI elements or workflows, but ensure they are clear, |
| 98 | + relevant, and add value to the content. |
| 99 | +- Don't use images of text, code samples, or terminal output. Use actual text so |
| 100 | + readers can copy/paste and find the contents via search engines. |
| 101 | +- Add alt text to images to describe their content and purpose. This improves |
| 102 | + accessibility for users with visual impairments. |
| 103 | + |
| 104 | +### Examples |
| 105 | + |
| 106 | +- Use examples to clarify complex concepts or demonstrate how to use a feature. |
| 107 | +- Prefer practical, real-world examples over abstract or contrived ones. |
| 108 | + |
| 109 | +### Formatting |
| 110 | + |
| 111 | +- Bold: use when referring to UI elements; prefer bold over quotes. |
| 112 | +- Italics: emphasize particular words or phrases, such as when |
| 113 | + introducing/defining a term. |
| 114 | +- Underscore: do not use; reserved for links. |
| 115 | +- Use inline code formatting for short code elements, such as variable names, |
| 116 | + function names, or command-line options. |
| 117 | +- Use block code formatting for longer code snippets or examples. |
| 118 | + |
| 119 | +### Word list |
| 120 | + |
| 121 | +Common terms used in this project: |
| 122 | + |
| 123 | +- ToolHive - this project, an open source tool that helps you run and manage MCP |
| 124 | + servers easily and securely |
| 125 | +- Stacklok - the company behind ToolHive |
| 126 | +- GitHub Copilot |
| 127 | +- Model Context Protocol (MCP) |
| 128 | +- open source (not "open-source") |
| 129 | +- large language model (LLM) |
| 130 | +- Visual Studio Code ("VS Code" after first use) |
| 131 | + |
| 132 | +Check this list for consistent use within the documentation. If you find |
| 133 | +inconsistencies, update the text to match the preferred term. If you find a term |
| 134 | +that is not listed here, consider adding it to the list for future reference. |
| 135 | + |
| 136 | +## Markdown style |
| 137 | + |
| 138 | +Prettier and markdownlint are used to enforce the following Markdown style |
| 139 | +conventions. |
| 140 | + |
| 141 | +- Headings: use "ATX-style" headings |
| 142 | +- Use unique headings within a document |
| 143 | +- Unordered lists: use hyphens (`-`), not asterisks (`*`) |
| 144 | +- Bold: Use the `**` syntax for bold text, not `__` |
| 145 | +- Italics: Use the `__` syntax for italic text, not `*` |
| 146 | +- Ordered lists: use lazy numbering for long or verbose lists. |
| 147 | + - Note: this is a "soft" recommendation. It is also intended only for Markdown |
| 148 | + documents that are read through a rendering engine. If the Markdown will be |
| 149 | + consumed in raw form like a repo README file, use real numbering. |
| 150 | +- Code blocks: use fenced code blocks (` ``` ` to begin/end) and always declare |
| 151 | + the language. If the language is unknown or plain text like log output, use |
| 152 | + `text` as the language. |
| 153 | +- Add blank lines around headings, lists, and code blocks. |
| 154 | +- No trailing whitespace on lines. |
| 155 | + - Use the `\` character at the end of a line for a single-line break, not the |
| 156 | + two-space syntax which is easy to miss. Exception: |
| 157 | +- Line limit: wrap lines at 80 characters; exceptions for links, tables, |
| 158 | + headings, and code blocks |
| 159 | + |
| 160 | +### Docusaurus specifics |
| 161 | + |
| 162 | +This website is built using Docusaurus, which has some specific requirements and |
| 163 | +conventions for Markdown files: |
| 164 | + |
| 165 | +- Heading 1 is reserved for the page title, typically defined in the Markdown |
| 166 | + front matter section. Sections within a page begin with Heading 2 (`##`). |
| 167 | +- Use relative file links (with .md/.mdx extensions) when referring to other |
| 168 | + pages. |
| 169 | +- Use the .mdx extension for pages containing JSX includes. |
| 170 | +- Use the front matter section on all pages. At a minimum, set the `title` (this |
| 171 | + is rendered into the page as an H1) and a short `description`. |
| 172 | +- Use the `admonition` component for notes, tips, warnings, and other |
| 173 | + annotations. This provides a consistent look and feel across the site. |
| 174 | + - Use the `:::type` syntax to define the admonition type, such as `note`, |
| 175 | + `tip`, `info`, `warning`, or `danger`. |
| 176 | +- Place images in `static/img` using WebP, PNG, or SVG format. |
| 177 | +- Use the `ThemedImage` component to provide both light and dark mode |
| 178 | + screenshots for apps/UIs that support both. |
| 179 | +- Use the `Tabs` and `TabItem` components to create tabbed content sections. |
0 commit comments