updates README and reorganizes directory

README.md

@@ -36,6 +36,78 @@ Mapping custom domains is not static anymore, but can be done with DNS:
 
 Certificates are generated, updated and cleaned up automatically via Let's Encrypt through a TLS challenge.
 
+### Documentation serve and build locally
+
+Pages uses [`mdBook`](https://rust-lang.github.io/mdBook/) and [`mdbook-toc`](https://github.com/badboy/mdbook-toc) to build and serve its documentation. Some section of the documentation have been referenced here for ease of use. 
+
+[`mdBook` Installation](https://rust-lang.github.io/mdBook/guide/installation.html)
+[`mdbook-toc` Installation](https://github.com/badboy/mdbook-toc)
+
+Once installed and sourced users may `mdbook serve pages-server/doc/` from a terminal of their choosing.
+
+### Documentation linting 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.
+
+The URL to the documentation preview looks like
+`http://localhost:4321/docs/{branch}/` where `{branch}` is the
+name of the current branch from which the preview is run.
+
+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, use 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.
+
 ## Chat for admins & devs
 
 [matrix: #gitea-pages-server:matrix.org](https://matrix.to/#/#gitea-pages-server:matrix.org)