readme: add instructions for using dev tooling

README.md

@@ -16,10 +16,86 @@ Current release branches are as follows:
 - [`v1.20`](https://codeberg.org/forgejo/docs/src/branch/v1.20)
 - [`v1.19`](https://codeberg.org/forgejo/docs/src/branch/v1.19)
 
-Documentation content lives in the `docs` subfolder, and images in the `images` subfolder.
+Documentation content lives in the `docs` directory, and images in the `docs/_images` subdirectory.
 
 ## Contributing
 
+### Tooling
+
+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.
+
 ### Pull Requests
 
 PRs should usually be sent against the [`next`](https://codeberg.org/forgejo/docs/src/branch/next) branch.
@@ -27,7 +103,7 @@ Sometimes it will be appropriate to send a PR against a specific release branch
 
 Most changes should either be sent as a _single commit per PR_, or should be squashed before merging.
 _Fast-forwarding is the preferred merge strategy._
-Changes can then be backported (or if appropriate frontported) by cherry-picking.
+Changes can then be [backported](#backports) (or if appropriate frontported) by cherry-picking.
 
 Rarely, it will make sense to create a feature branch containting a series of commits that will
 be merged instead of squashing and fast-forwarding.
@@ -52,28 +128,23 @@ This is currently necessary due to technical limitations with Forgejo Actions. I
 access, you may fork this repository and send a pull request the usual way, but a live preview of the
 website will not be available.
 
-### Backports
+#### Backports
 
-If a commit is meant to be backported to a stable branch, it must be
+If a PR is meant to be backported to a stable branch, it must be
 labelled with `backport/v1.20`, `backport/v1.19`, etc.
 
-### Previewing changes
+### Content guidelines
 
-Run `pnpm run preview` to clone the [website repo](https://codeberg.org/forgejo/forgejo)
+#### Links
-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.
-
-### Links
 
 All internal links within the documentation content should be relative to each page's path
 at the `https://forgejo.org/docs/{{version}}/` URL.
 File extensions (`.md`) should not be included, and every URL should end with a trailing slash.
 Look at existing links for examples.
 
-### Images
+#### Images
 
-Images should use relative URLs to the image files, which will be published at `https://forgejo.org/images/{{version}}/`.
+Images should be stored in the `docs/_images/` directory, and should be referenced by their path relative to the markdown files where they are used.
 
 ## Code of Conduct
 

package.json

@@ -8,6 +8,7 @@
   "scripts": {
     "preview": "./scripts/preview.sh",
     "test": "echo \"Error: no test specified\" && exit 1",
+    "lint": "pnpm run lint:remark && pnpm run lint:prettier",
     "lint:remark": "remark . --quiet --frail",
     "lint:prettier": "prettier --check .",
     "format:remark": "remark . --quiet --frail --output",