36fb2be926
Docs under website/docs were linked with Docusaurus site routes (`](/getting-started/installation)`, `](/docs/user-guide/x)`), which GitHub's file viewer resolves as repository paths and 404s (#114428). Relative Markdown file links (`](../user-guide/x.md#anchor)`) are followed by both GitHub and Docusaurus, so that becomes the authoring convention: - website/scripts/check_doc_links.py lints hand-authored EN + zh-Hans pages for route-style links (`--fix` rewrites them, refusing any route that maps to no doc file); wired into the Docs Site Checks workflow and tests/website/test_check_doc_links.py. - generate-skill-docs.py emits the same relative form for related-skill and catalog links instead of `/docs/user-guide/skills/...`. - src/remark/relativeDocLinks.js rewrites `./x.md`/`../x.md` to content-root-absolute `/x.md` before Docusaurus resolves links, so a relative link still resolves in the zh-Hans build when source and target sit on different sides of the translation fallback (Docusaurus resolves `./`/`../` only against the source file's own directory). - website/README.md states the convention and points at the checker.
65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
# Website
|
|
|
|
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
|
|
|
|
> **Reading the docs on GitHub?** The Markdown under `docs/` is authored for the rendered site at
|
|
> <https://hermes-agent.nousresearch.com/docs/>. Cross-page links are relative Markdown paths, so they
|
|
> follow through on GitHub's file viewer too. Every page on the site has an **Edit this page** link
|
|
> that opens the source file here.
|
|
|
|
## Authoring links in `docs/`
|
|
|
|
- Link to another page with a relative Markdown path, anchors included:
|
|
`[Profiles](../user-guide/profiles.md)`, `[Bundles](../user-guide/features/skills.md#skill-bundles)`.
|
|
Docusaurus turns the file path into the page route; GitHub follows the same path. Site routes
|
|
(`/user-guide/profiles`, `/docs/user-guide/profiles`) only work on the rendered site — GitHub
|
|
resolves them as repository paths and 404s, and the `/docs/` form also emits
|
|
`/docs/zh-Hans/docs/...` 404s in the zh-Hans build because `baseUrl` is already `/docs/`.
|
|
- `python3 website/scripts/check_doc_links.py` fails on any route-style link in hand-authored pages
|
|
(EN and the zh-Hans mirror); `--fix` rewrites them. It runs in the `Docs Site Checks` workflow.
|
|
Generated pages (`user-guide/skills/{bundled,optional}`, `reference/*skills-catalog.md`) are
|
|
produced by `scripts/generate-skill-docs.py`, which emits the same relative form.
|
|
- Pin `{#anchor}` on cross-linked headings so the zh-Hans mirror keeps the same id.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
yarn
|
|
```
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
yarn start
|
|
```
|
|
|
|
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
|
|
|
## Build
|
|
|
|
```bash
|
|
yarn build
|
|
```
|
|
|
|
This command generates static content into the `build` directory and can be served using any static contents hosting service.
|
|
|
|
## Deployment
|
|
|
|
Using SSH:
|
|
|
|
```bash
|
|
USE_SSH=true yarn deploy
|
|
```
|
|
|
|
Not using SSH:
|
|
|
|
```bash
|
|
GIT_USER=<Your GitHub username> yarn deploy
|
|
```
|
|
|
|
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
|
|
|
|
## Diagram Linting
|
|
|
|
CI runs `ascii-guard` to lint docs for ASCII box diagrams. Use Mermaid (````mermaid`) or plain lists/tables instead of ASCII boxes to avoid CI failures.
|