wehub-resource-sync
79031da543
Spell checking / Check Spelling (push) Has been cancelled
Spell checking / Update PR (push) Has been cancelled
Publish Dev Docs Website / build (push) Failing after 1s
Publish Dev Docs Website / deploy (push) Has been skipped
Spell checking / Report (Push) (push) Has been cancelled
Spell checking / Report (PR) (push) Has been cancelled
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
|
|
```
|