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 bun installed on your system. You can check by running bun -v in your terminal.

If the bun command is not recognized by your terminal after a successful installation and restarting the terminal, follow these steps to add it manually to your system PATH: How to add bun to your PATH

If bun has been successfully installed, you can go to the website folder in your terminal (by running cd website) and run bun install and then bun 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.

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 root of the project, from a terminal:

Command	Action
bun install	Installs dependencies
bun dev	Starts local dev server at localhost:4321
bun build	Build your production site to ./dist/
bun preview	Preview your build locally, before deploying
bun astro ...	Run CLI commands like astro add, astro check
bun 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

bun dev command doesn’t work

Run the following command: bun astro 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, run the following command: bun playwright install --with-deps chromium