# Contributing documentation

Alice Linux documentation lives in the `docs/` directory of the [main repository](https://codeberg.org/emmett1/alicelinux). Improvements, corrections, and new guides are welcome.

## Editing existing docs

Pick a file from `docs/`, make your changes, and submit a pull request. Each doc is a standard markdown file that gets converted to HTML by `utils/buildsite.sh`.

Docs use numbered prefixes (`01-`, `02-`, etc.) to define reading order. If you insert a new doc between existing ones, renumber as needed so the sequence stays consistent.

## Adding a new doc

Create a new markdown file in `docs/` with the next available number prefix. The first line must be an ATX heading (`# Title`) -- this is what appears in the docs index and the next-doc navigation link.

Keep the scope focused. If the topic is already covered by an existing doc, expand that doc instead of creating a competing one.

## Style conventions

- Follow standard markdown format.
- Avoid tables.

## Previewing locally

Run `./utils/buildsite.sh` from the repo root (requires `cmark` and `curl`). Start a local server to view the result:

```
busybox httpd -p 8080 -h public
```

Then open `http://localhost:8080` in a browser.

## Submitting changes

1. Fork the repository on Codeberg.
2. Make your changes in a feature branch.
3. Run `./utils/buildsite.sh` and verify the output.
4. Submit a pull request against the `main` branch.