FOSSBilling Docs

This repository contains the official documentation site for FOSSBilling.

The site is built with Astro, Starlight, and Markdoc. It is published at https://docs.fossbilling.org.

Local Development

npm install
npm run dev

The site will be available at http://localhost:4321.

Before opening a pull request, run:

npm run format
npm run check
npm run build

Commands

Command	Action
npm install	Install dependencies
npm run dev	Start the local dev server at localhost:4321
npm run check	Run Astro diagnostics
npm run build	Build the production site to ./dist/
npm run preview	Preview the production build locally
npm run format	Format Astro, CSS, JS, TS, MJS, and JSON files
npm run format:check	Check formatting without writing changes

For Cloudflare deployments with Wrangler, run npm run build first so ./dist/ exists before wrangler deploy.

Pull requests to main are also validated in CI with formatting checks, astro check, and a production build.

Project Structure

.
├── astro.config.mjs    # Astro, Starlight, sidebar, social links, redirects
├── markdoc.config.mjs  # Starlight Markdoc integration
├── public/             # Static files copied as-is
src/
├── assets/             # Bundled images and logos used by docs pages
├── components/         # Starlight component overrides
├── content/
│   └── docs/           # Documentation pages
└── styles/             # Site-wide custom CSS

Editing Content

Documentation pages live in src/content/docs/ and use .mdoc files.

Each page should include frontmatter:

---
title: Page title
description: Short page description.
---

Use section overview pages named index.mdoc where a sidebar section needs a landing page.

Prefer absolute internal links with trailing slashes, for example:

[Installation](/getting-started/installation/)

When routes move, update internal links to the new route. Keep legacy redirects in astro.config.mjs when an old public docs URL should continue to work.

Images and Assets

Use src/assets/ for images referenced by documentation pages. This lets Astro optimize and fingerprint assets during the build.

Reference bundled images with relative paths from the content file:

![Installer landing page](../../../assets/guides/install/installer-landing.png)

Use public/ only for files that must be served exactly as-is from the site root, such as favicon.svg or deployment metadata.

Navigation

The sidebar is configured in astro.config.mjs.

Some sections are autogenerated from folders, while larger sections use explicit ordering so the sidebar remains predictable. When adding a new page, check whether the section uses autogenerate or a manually listed item.

Redirects

astro.config.mjs includes redirects from older documentation routes to the current Starlight routes. Do not remove these just because the old route is no longer present in src/content/docs/; they preserve inbound links from the previous docs site.

Deployment

The production build outputs static files to dist/.

npm run build

Deployments use Cloudflare/Wrangler configuration from wrangler.jsonc.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Run npm run format, npm run check, and npm run build.
5. Submit a pull request.

Licensing

Code, configuration, and build tooling in this repository are licensed under the GNU Affero General Public License v3.0 or later. See LICENSE.

Documentation content is licensed under Creative Commons Attribution-ShareAlike 4.0 International. See LICENSE-docs.

Unless otherwise noted, the documentation license applies to:

• src/content/docs/**
• src/assets/**

Logos, wordmarks, trademarks, and other brand assets are not licensed under CC BY-SA 4.0. Third-party marks remain subject to their respective owners' rights.

Links

• FOSSBilling GitHub
• Starlight Documentation
• Astro Documentation