It is possible to simply edit the documentation with a text editor and [send PRs](#pull-requests) without using any other tooling.
[Lints](#linting-and-formatting) will be run when PRs are sent to ensure that content and code comply with our stylistic rules.
However, several tools are available to run locally to help ensure that content is [formatted](#linting-and-formatting) appropriately before committing,
as well as to [preview](#previewing-changes) your changes on a local copy of the Forgejo website.
#### Getting set up
To run the tools used in this repo you will need [NodeJS](https://nodejs.org/en/download) on your machine.
The required version will change over time, but in general it is recommended to use at least the latest LTR release.
You'll also need [PNPM](https://pnpm.io/installation). The easiest way to install it on most systems is to use the
command `corepack enable`, which is part of NodeJS. However depending on your system you may prefer to use a package manager.
Once you have Node and PNPM installed, just run `pnpm install` from the root of this repo to fetch the dependencies
and set up the Git [pre-commit hook](#pre-commit-hook).
```shell
# Install/enable PNPM
corepack enable
# Clone this repo (or your fork of it)
git clone git@codeberg.org:forgejo/docs
cd docs
# Install the dependencies
pnpm install
```
Every time you `pull` the repo or `checkout` a different branch, you should run `pnpm install` again to update the dependencies.
#### Previewing changes
```shell
pnpm run preview
```
This command will clone the [website repo](https://codeberg.org/forgejo/forgejo)
and launch a local development server. The current docs branch will be opened in the browser.
Modifications can be made to the docs while the dev server is running, and the preview will live-reload.
#### Linting and formatting
We use two linters to check that all content is formatted in a consistent way.
Most of the rules are checked using [remark-lint](https://github.com/remarkjs/remark-lint),
whilst some stylistic consistency is enforced using [Prettier](https://prettier.io/).
To run both linters and display any warnings in the terminal, use the following command:
```shell
pnpm run lint
```
Prettier is also able to automatically format the code according to its rules.
To do so, ue the following command.
Be aware that it can occasionally break things, so be sure to check what it changes.
```shell
pnpm run format:prettier
```
There is currently no way to automatically format the code to according to the rules configured for `remark-lint`,
however the pre-commit hook should prevent badly-formatted content from being committed.
#### Pre-commit hook
Both of the above linting and formatting commands are run automatically on commit
using a Git `pre-commit` hook which is set up when running `pnpm install`.
This attempts to prevent badly-formatted content from being committed.
In the event that the pre-commit hook is skipped or fails to run, badly-formatted
content will also be caught by the CI, preventing the PR from being merged.
