chore: import upstream snapshot with attribution
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
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
This commit is contained in:
@@ -0,0 +1,44 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user