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.
1.9 KiB
Dev Docs Website
This folder hosts the docmd project that turns the PowerToys developer
documentation in doc/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 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. 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 sitedocmd-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 bundledgithub-source-linksplugin rewrites them tohttps://github.com/microsoft/PowerToys/blob/main/...on the published site.
Building locally
Requires Node.js.
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