Skip to content

Commit 77164f0

Browse files
danbarrdanbarr
authored
Repo quality of life maintenance and fixes (#381)
* Bump devcontainer to Debian trixie * Fix minimumReleaseAge handling Not supported with GitHub Actions digests or with some container registries (ghcr and mcr included) * Normalize node version handling - Reduce noise by configuring Renovate to replace (i.e. 22->24) instead of bumping (i.e. 24->24.11.1 like it wanted to do to .nvmrc) - Simplify range in package.json so Renovate doesn't widen - Use .nvmrc for the setup-node action to reduce touchpoints * Improve LLM instructions * Fix some random formatting * Fix PR template list again The "*" trick didn't work, GitHub still turned them into tasks. --------- Signed-off-by: Dan Barr <6922515+danbarr@users.noreply.github.com> Co-authored-by: Dan Barr <6922515+danbarr@users.noreply.github.com>
1 parent 05f38a2 commit 77164f0

File tree

11 files changed

+185
-59
lines changed

11 files changed

+185
-59
lines changed

‎.devcontainer/devcontainer.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
{
22
"name": "Docusaurus",
3-
"image": "mcr.microsoft.com/devcontainers/typescript-node:24-bookworm",
3+
"image": "mcr.microsoft.com/devcontainers/typescript-node:24-trixie",
44
"features": {
5-
"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
5+
"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {
6+
"moby": false
7+
}
68
},
79
"forwardPorts": [3000],
810
"remoteUser": "node",

‎.github/copilot-instructions.md‎

Lines changed: 72 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Project overview
22

3-
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.
3+
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.
4+
5+
## Tech stack
6+
7+
- Docusaurus 3, based on React 19 and TypeScript
8+
- Node.js 24 (exact version required - see `package.json` engines field)
9+
- npm for package management
10+
- Vercel for deployment and hosting
411

512
## Folder structure
613

@@ -15,28 +22,79 @@ This is the user-facing documentation for ToolHive, an open source tool that hel
1522
- `/sidebars.ts`: defines the structure of the documentation sidebar, including which pages appear in the sidebar and their order.
1623
- `/vercel.json`: configuration file for Vercel deployment, specifying build settings and redirects.
1724

18-
## Libraries and tools
25+
## Commands
26+
27+
Development commands:
28+
29+
- `npm run start`: starts a local development server with hot reloading.
30+
- `npm run build`: runs a production build of the site to verify there are no build errors. Run this before creating a PR to ensure the site builds successfully.
31+
32+
Code quality commands (note: pre-commit hooks run these automatically on staged files):
33+
34+
- `npm run prettier` and `npm run prettier:fix`: check and fix code formatting issues (all file types).
35+
- `npm run eslint` and `npm run eslint:fix`: check and fix code quality issues (`.js`, `.jsx`, `.ts`, `.tsx`, `.mdx` files only).
36+
- `npm run markdownlint` and `npm run markdownlint:fix`: check and fix Markdown style issues (`.md` files only - DO NOT use with `.mdx` files).
37+
38+
## Contribution guidelines
39+
40+
- Use the GitHub flow for contributions: create a branch, make changes, open a pull request (PR).
41+
- Use the pull request template (`/.github/pull_request_template.md`) when opening a PR on behalf of the user.
42+
- Ensure all changes pass linting and formatting checks before submitting a PR.
43+
- Write concise commit messages, limited to 50 characters for the subject line, with a detailed body only if necessary.
44+
- Do NOT use conventional commits style; use imperative mood in the subject line (e.g., "Add", "Fix", "Update").
45+
46+
## Automated quality checks
47+
48+
The project uses automated tooling to enforce code quality and formatting standards:
1949

20-
- Docusaurus for the documentation site framework.
21-
- React and TypeScript for building custom components and pages.
22-
- npm for package management.
23-
- Vercel for deployment and hosting.
50+
- **Pre-commit hooks**: lint-staged runs automatically on `git commit`, applying prettier and appropriate linters to staged files.
51+
- **GitHub Actions**: All PRs trigger automated checks (ESLint, markdownlint, Prettier).
52+
- **No manual formatting needed**: The pre-commit hook handles formatting automatically - you do not need to run formatters manually.
2453

25-
Code quality tools:
54+
File type to linter mapping (handled automatically by pre-commit hooks):
2655

27-
- All files: Prettier for code formatting - `npm run prettier` to check, `npm run prettier:fix` to auto-fix.
28-
- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` to check, `npm run markdownlint:fix` to auto-fix (`.md` files only).
29-
- ESLint for JavaScript/TypeScript and MDX linting - `npm run eslint` to check, `npm run eslint:fix` to auto-fix.
56+
- `.md` files: Prettier + markdownlint
57+
- `.mdx` files: Prettier + ESLint (NOT markdownlint)
58+
- `.js`, `.jsx`, `.ts`, `.tsx` files: Prettier + ESLint
59+
- `.css`, `.json`, `.jsonc`, `.yaml`, `.yml` files: Prettier only
60+
61+
## Git workflow
62+
63+
- **Main branch**: `main` - all feature branches should be created from and merged into main
64+
- **Branch naming**: Use descriptive names (e.g., `fix-broken-link`, `add-vmcp-docs`)
65+
- **Pre-commit hooks**: Automatically format and lint staged files on commit
66+
- **Before pushing**: Run `npm run build` to verify the site builds successfully
67+
- **Default branch for PRs**: Target `main` unless working on a specific release branch
3068

3169
## Audience
3270

3371
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.
3472

3573
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.
3674

75+
## Information architecture
76+
77+
This project follows the [Diataxis framework](https://diataxis.fr/) for documentation organization. Diataxis divides documentation into four types based on user needs:
78+
79+
1. **Tutorials** (`/docs/toolhive/tutorials/`) - Learning-oriented, step-by-step lessons that guide users through completing a project or learning a concept.
80+
2. **How-to guides** (`/docs/toolhive/guides-*/`) - Task-oriented, practical guides that show how to solve specific problems or accomplish specific tasks.
81+
3. **Reference** (`/docs/toolhive/reference/`) - Information-oriented, technical descriptions of the machinery and how to operate it (API docs, CLI commands, configuration options).
82+
4. **Explanation/Concepts** (`/docs/toolhive/concepts/`) - Understanding-oriented, explanations that clarify and illuminate topics, provide background and context.
83+
84+
### When to create new pages
85+
86+
Create a new documentation page when:
87+
88+
- The content addresses a distinct task, concept, or reference topic that doesn't fit within existing pages.
89+
- An existing page would become too long or cover too many disparate topics.
90+
- The information architecture requires it (e.g., a new MCP server guide, a new tutorial).
91+
- The content belongs to a different Diataxis category than existing content.
92+
93+
Always consider where the new page fits in the Diataxis framework and place it in the appropriate directory. Update `/sidebars.ts` to include the new page in the navigation.
94+
3795
## Review process
3896

39-
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.
97+
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.
4098

4199
- Prioritize clarity, accuracy, and consistency.
42100
- Ensure that the content is easy to understand, follows the writing style guide.
@@ -100,7 +158,7 @@ The project's official language is US English.
100158

101159
### Word list
102160

103-
Common terms used in this project:
161+
ALWAYS use these exact terms and capitalizations. When editing documentation, replace any variations with the preferred terms listed here:
104162

105163
- ToolHive - this project, an open source tool that helps you run and manage MCP servers easily and securely
106164
- Stacklok - the company behind ToolHive
@@ -111,7 +169,7 @@ Common terms used in this project:
111169
- Visual Studio Code ("VS Code" after first use)
112170
- Virtual MCP Server (vMCP) - a feature of ToolHive that aggregates multiple MCP servers into a single endpoint; use "Virtual MCP Server (vMCP)" on first use, "vMCP" thereafter
113171

114-
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.
172+
If you encounter a term not listed here that appears frequently in the documentation, consider adding it to this list for consistency.
115173

116174
## Markdown style
117175

@@ -127,7 +185,7 @@ Prettier and markdownlint are used to enforce the following Markdown style conve
127185
- 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.
128186
- Add blank lines around headings, lists, and code blocks.
129187
- No trailing whitespace on lines.
130-
- 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:
188+
- Use the `\` character at the end of a line for a single-line break, not the two-space syntax which is easy to miss.
131189
- Line limit: wrap lines at 80 characters; exceptions for links, tables, headings, and code blocks
132190

133191
### Docusaurus specifics

‎.github/pull_request_template.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
<!-- Explain what has changed and why -->
33

44
### Type of change
5+
<!-- Keep the one that applies and delete the others -->
56

6-
* [ ] New documentation
7-
* [ ] Documentation update
8-
* [ ] Bug fix (typo, broken link, etc.)
9-
* [ ] Navigation/structure change
7+
- New documentation
8+
- Documentation update
9+
- Bug fix (typo, broken link, etc.)
10+
- Navigation/structure change
1011

1112
### Related issues/PRs
1213
<!-- Reference related issues the PR is related to or will resolve -->

‎.github/workflows/_security-checks.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ jobs:
3434
- name: Set up Node.js
3535
uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6
3636
with:
37-
node-version: '24.11.1'
37+
node-version-file: '.nvmrc'
3838

3939
- name: Run npm audit
4040
run: npm audit --omit=dev --audit-level=moderate

‎.markdownlint-cli2.jsonc‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
11
{
22
"gitignore": true,
33
"globs": ["**/*.md"],
4-
"ignores": [
5-
"docs/toolhive/reference/cli/",
6-
"static/api-specs/*.md",
7-
".github/pull_request_template.md",
8-
],
4+
"ignores": ["docs/toolhive/reference/cli/", "static/api-specs/*.md"],
95
}

‎AGENTS.md‎

Lines changed: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
# Project overview
22

3-
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.
3+
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.
4+
5+
## Tech stack
6+
7+
- Docusaurus 3, based on React 19 and TypeScript
8+
- Node.js 24 (exact version required - see `package.json` engines field)
9+
- npm for package management
10+
- Vercel for deployment and hosting
411

512
## Folder structure
613

@@ -15,25 +22,76 @@ This is the user-facing documentation for ToolHive, an open source tool that hel
1522
- `/sidebars.ts`: defines the structure of the documentation sidebar, including which pages appear in the sidebar and their order.
1623
- `/vercel.json`: configuration file for Vercel deployment, specifying build settings and redirects.
1724

18-
## Libraries and tools
25+
## Commands
26+
27+
Development commands:
28+
29+
- `npm run start`: starts a local development server with hot reloading.
30+
- `npm run build`: runs a production build of the site to verify there are no build errors. Run this before creating a PR to ensure the site builds successfully.
31+
32+
Code quality commands (note: pre-commit hooks run these automatically on staged files):
33+
34+
- `npm run prettier` and `npm run prettier:fix`: check and fix code formatting issues (all file types).
35+
- `npm run eslint` and `npm run eslint:fix`: check and fix code quality issues (`.js`, `.jsx`, `.ts`, `.tsx`, `.mdx` files only).
36+
- `npm run markdownlint` and `npm run markdownlint:fix`: check and fix Markdown style issues (`.md` files only - DO NOT use with `.mdx` files).
37+
38+
## Contribution guidelines
39+
40+
- Use the GitHub flow for contributions: create a branch, make changes, open a pull request (PR).
41+
- Use the pull request template (`/.github/pull_request_template.md`) when opening a PR on behalf of the user.
42+
- Ensure all changes pass linting and formatting checks before submitting a PR.
43+
- Write concise commit messages, limited to 50 characters for the subject line, with a detailed body only if necessary.
44+
- Do NOT use conventional commits style; use imperative mood in the subject line (e.g., "Add", "Fix", "Update").
45+
46+
## Automated quality checks
47+
48+
The project uses automated tooling to enforce code quality and formatting standards:
1949

20-
- Docusaurus for the documentation site framework.
21-
- React and TypeScript for building custom components and pages.
22-
- npm for package management.
23-
- Vercel for deployment and hosting.
50+
- **Pre-commit hooks**: lint-staged runs automatically on `git commit`, applying prettier and appropriate linters to staged files.
51+
- **GitHub Actions**: All PRs trigger automated checks (ESLint, markdownlint, Prettier).
52+
- **No manual formatting needed**: The pre-commit hook handles formatting automatically - you do not need to run formatters manually.
2453

25-
Code quality tools:
54+
File type to linter mapping (handled automatically by pre-commit hooks):
2655

27-
- All files: Prettier for code formatting - `npm run prettier` to check, `npm run prettier:fix` to auto-fix.
28-
- markdownlint for enforcing Markdown style conventions - `npm run markdownlint` to check, `npm run markdownlint:fix` to auto-fix (`.md` files only).
29-
- ESLint for JavaScript/TypeScript and MDX linting - `npm run eslint` to check, `npm run eslint:fix` to auto-fix.
56+
- `.md` files: Prettier + markdownlint
57+
- `.mdx` files: Prettier + ESLint (NOT markdownlint)
58+
- `.js`, `.jsx`, `.ts`, `.tsx` files: Prettier + ESLint
59+
- `.css`, `.json`, `.jsonc`, `.yaml`, `.yml` files: Prettier only
60+
61+
## Git workflow
62+
63+
- **Main branch**: `main` - all feature branches should be created from and merged into main
64+
- **Branch naming**: Use descriptive names (e.g., `fix-broken-link`, `add-vmcp-docs`)
65+
- **Pre-commit hooks**: Automatically format and lint staged files on commit
66+
- **Before pushing**: Run `npm run build` to verify the site builds successfully
67+
- **Default branch for PRs**: Target `main` unless working on a specific release branch
3068

3169
## Audience
3270

3371
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.
3472

3573
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.
3674

75+
## Information architecture
76+
77+
This project follows the [Diataxis framework](https://diataxis.fr/) for documentation organization. Diataxis divides documentation into four types based on user needs:
78+
79+
1. **Tutorials** (`/docs/toolhive/tutorials/`) - Learning-oriented, step-by-step lessons that guide users through completing a project or learning a concept.
80+
2. **How-to guides** (`/docs/toolhive/guides-*/`) - Task-oriented, practical guides that show how to solve specific problems or accomplish specific tasks.
81+
3. **Reference** (`/docs/toolhive/reference/`) - Information-oriented, technical descriptions of the machinery and how to operate it (API docs, CLI commands, configuration options).
82+
4. **Explanation/Concepts** (`/docs/toolhive/concepts/`) - Understanding-oriented, explanations that clarify and illuminate topics, provide background and context.
83+
84+
### When to create new pages
85+
86+
Create a new documentation page when:
87+
88+
- The content addresses a distinct task, concept, or reference topic that doesn't fit within existing pages.
89+
- An existing page would become too long or cover too many disparate topics.
90+
- The information architecture requires it (e.g., a new MCP server guide, a new tutorial).
91+
- The content belongs to a different Diataxis category than existing content.
92+
93+
Always consider where the new page fits in the Diataxis framework and place it in the appropriate directory. Update `/sidebars.ts` to include the new page in the navigation.
94+
3795
## Review process
3896

3997
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.
@@ -100,7 +158,7 @@ The project's official language is US English.
100158

101159
### Word list
102160

103-
Common terms used in this project:
161+
ALWAYS use these exact terms and capitalizations. When editing documentation, replace any variations with the preferred terms listed here:
104162

105163
- ToolHive - this project, an open source tool that helps you run and manage MCP servers easily and securely
106164
- Stacklok - the company behind ToolHive
@@ -111,7 +169,7 @@ Common terms used in this project:
111169
- Visual Studio Code ("VS Code" after first use)
112170
- Virtual MCP Server (vMCP) - a feature of ToolHive that aggregates multiple MCP servers into a single endpoint; use "Virtual MCP Server (vMCP)" on first use, "vMCP" thereafter
113171

114-
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.
172+
If you encounter a term not listed here that appears frequently in the documentation, consider adding it to this list for consistency.
115173

116174
## Markdown style
117175

@@ -127,7 +185,7 @@ Prettier and markdownlint are used to enforce the following Markdown style conve
127185
- 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.
128186
- Add blank lines around headings, lists, and code blocks.
129187
- No trailing whitespace on lines.
130-
- 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:
188+
- Use the `\` character at the end of a line for a single-line break, not the two-space syntax which is easy to miss.
131189
- Line limit: wrap lines at 80 characters; exceptions for links, tables, headings, and code blocks
132190

133191
### Docusaurus specifics

0 commit comments

Comments
 (0)