mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-09-02 04:01:25 +02:00
e3a1ee2e5b
This pull request adds a custom `docmd` plugin to improve how documentation links to source files are handled, ensuring that repo-root-relative links work both when editing locally and on the published site. The main changes include introducing the new plugin, updating configuration to use it, and documenting its behavior. **Plugin integration and configuration:** * Added a new local plugin `github-source-links` in `docmd-plugins/`, which rewrites repo-root-relative links (e.g., `/src/.../Foo.cpp`) in Markdown files to absolute GitHub blob URLs during the documentation build process, ensuring links remain functional on the published site. [[1]](diffhunk://#diff-c2c746e6974a6cfdd229031c2977f2bb0dca37c6d5f598ed45dc0d9f0b74c7caR1-R52) [[2]](diffhunk://#diff-a97f3ce59c97313aacd716b9874b445d162c45ee2e6ef9fd2db59fe17235e1cfR1-R8) * Updated `docmd.config.json` to register the new plugin under the `plugins` key, enabling it for documentation builds. * Updated `package.json` to include the plugin as a dependency, referencing the local plugin directory. **Documentation updates:** * Updated `README.md` to document the new `docmd-plugins/` folder, explain the purpose of repo-root-relative links, and describe how the plugin rewrites these links for the published site.
45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
# Dev Docs Website
|
|
|
|
This folder hosts the [docmd](https://docmd.io/) project that turns the PowerToys developer
|
|
documentation in [`doc/devdocs`](../devdocs) into a static website.
|
|
|
|
## Generated site
|
|
|
|
The `site/` folder is the docmd build output. It is **not committed** to the repository — it is
|
|
git-ignored and rebuilt on demand. You only need it locally when previewing your changes (see below).
|
|
|
|
Publishing is handled by the
|
|
[Publish Dev Docs Website](../../.github/workflows/regenerate-devdocs-website.yml) GitHub Action, which
|
|
runs whenever files under `doc/devdocs` (or this folder) change on the `main` branch — it can also
|
|
be triggered manually from the **Actions** tab. The action builds the site and deploys it straight to
|
|
GitHub Pages as an artifact, so nothing is written back to the repository.
|
|
|
|
> [!NOTE]
|
|
> The action requires GitHub Pages to be enabled with **Source: GitHub Actions** under the repository
|
|
> **Settings → Pages**.
|
|
|
|
## Editing the docs
|
|
|
|
To change the documentation, edit the Markdown files under [`doc/devdocs`](../devdocs). The remaining
|
|
files in this folder are maintained by hand and are safe to edit:
|
|
|
|
- `docmd.config.json` — docmd configuration (title, source, output, plugins)
|
|
- `package.json` — pins the docmd version used to build the site
|
|
- `docmd-plugins/` — local build-time docmd plugins
|
|
|
|
> [!TIP]
|
|
> Link to repository files with repo-root-relative paths such as `/src/modules/.../Foo.cpp`.
|
|
> VS Code resolves these against the workspace root (so they open the local file), and the
|
|
> bundled `github-source-links` plugin rewrites them to
|
|
> `https://github.com/microsoft/PowerToys/blob/main/...` on the published site.
|
|
|
|
## Building locally
|
|
|
|
Requires [Node.js](https://nodejs.org/).
|
|
|
|
```powershell
|
|
npm install # install dependencies (first time only)
|
|
npm run dev # start a local preview server at http://localhost:3000
|
|
npm run build # generate the static site into ./site
|
|
```
|