Getting Started

This page provides guidelines for contributing to the development of the official Deluge Community Firmware website, including adding content to existing website pages, and adding new pages.

Contributing

You’ll find an “Edit page” link at the bottom of each documentation page. Click this link to open the github.dev editor in your browser, where you can make changes to the documentation source files.

For more info, check the github.dev editor documentation!

For the basics on how to write documentation, check the Starlight documentation page on Authoring Content in Markdown! Even if you are a seasoned Markdown veteran, this page is a must-read so that you are aware of the cool extensions that Starlight has.

If you add new files to the docs folders, they will show up in the sidebar automatically.

Always use absolute paths for linking to other pages, the link validator will yell at you otherwise. E.g. [Features Overview](/features/community_features)

Always use relative paths for referencing images. Feel free to place images into a folder next to the documentation page that uses them. E.g. ![My Photo](../photo.jpg). The /src/assets folder can be used for more general use assets.

Write in .md or .mdx format. .md files are “pure” Markdown but with directives added. For example :key[...] can be used to reference Deluge shortcuts. .mdx files do everything that Markdown files can, but can also include Components. See the Starlight docs for more information.

Testing your changes

Using GitHub Pages on your fork

1. In your fork of the DelugeFirmware repository, go to the Actions tab.
2. Select the Deploy to GitHub Pages workflow.
3. Click Run workflow on the right
4. Select the branch you want to deploy
5. Click Run
6. Check https://your-github-username.github.io/DelugeFirmware/ to see your deployed website.

On your machine

Make sure that you have pnpm installed on your system. You can check by running pnpm -v in your terminal.

If pnpm has been successfully installed, go to the website folder in your terminal (cd website) and run pnpm install and then pnpm run dev (or pnpm dev). Once the dev server has started, you can open http://localhost:4321 in your browser. The page will automatically refresh with the changes you make.

If Playwright is not installed yet (required for Mermaid rendering during builds and for perf scripts), run: pnpm exec playwright install --with-deps chromium chromium-headless-shell

Deluge Companion performance guard (local only)

Run the local perf guard from the website folder:

• pnpm run perf:guard

This script runs the Deluge Companion performance probe and fails with a non-zero exit code if thresholds are exceeded. It is intentionally local-only and is not part of PR checks.

Useful options:

• Use an already-running site instead of auto-starting preview: PERF_URL=http://127.0.0.1:4322 pnpm run perf:guard
• Change probe run count: PERF_RUNS=5 pnpm run perf:guard
• Override thresholds: MAX_MEDIAN_INTERACTIVE_MS=1100 MAX_AVG_SCRIPT_TRANSFER_BYTES=120000 pnpm run perf:guard

Links

You most likely don’t have to worry about the base path, but if a link is not working on a fork, then this is probably the reason.

Links in Markdown (md, mdx) files automatically have the base path added. So if your home page is available at /DelugeFirmware, the link from the above example would be converted to /DelugeFirmware/features/community_features automatically during the build.

If you have links in a file that is not Markdown, you need to use the src/utils.ts utility function to ensure correct links are generated in all cases. See src/pages/index.astro for an example usage.

Doxygen

The ../.github/workflows/deploy-website.yml workflow deploys both the Starlight website and the developer documentation generated by Doxygen.

The Doxygen output gets copied to /website/public/doxygen, so don’t put anything there. Likewise, don’t put anything behind the /doxygen URL path within Starlight to avoid a collision.

---

Find the generated Starlight readme below. These are good resources to get you started. Starlight docs are great, don’t forget to use them!

🚀 Project Structure

Inside of your Astro + Starlight project, you’ll see the following folders and files:

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.

Images can be added to src/assets/ and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the public/ directory.

🧞 Commands

All commands are run from the website directory, from a terminal:

Command	Action
pnpm install	Installs dependencies
pnpm run dev (or pnpm dev)	Starts local dev server at localhost:4321
pnpm run build	Builds the production site to ./dist/
pnpm run preview	Builds and previews your site locally
pnpm run check	Runs Astro type/content checks, ESLint, and Prettier
pnpm run check:fix	Applies lint/format fixes
pnpm run perf:guard	Runs local Deluge Companion perf guard
pnpm exec playwright install --with-deps chromium chromium-headless-shell	Installs Playwright browsers/deps
pnpm astro ...	Runs Astro CLI commands like astro add
pnpm astro -- --help	Get help using the Astro CLI

👀 Want to learn more?

Check out Starlight’s docs, read the Astro documentation, or jump into the Astro Discord server.

Troubleshooting

pnpm dev command doesn’t work

Run pnpm install first, then use pnpm run dev (or pnpm dev).

error is displayed saying to run “npx playwright install”

The site uses playwright for generating the site previews and the mermaid diagrams.

To install Playwright browsers and required dependencies, run: pnpm exec playwright install --with-deps chromium chromium-headless-shell