The documentation you are reading right now is maintained by the BookWyrm community. Anyone can contribute to the docs.
You can report an error, suggest an improvement or request an addition to the documentation by creating an issue in the documentation repository.
The Documentation has its own GitHub repository. Documentation is written in Markdown and we use Jinja and a Python script to convert that into HTML. A Jinja plugin is used with Crowdin to create translations. All documentation source files should be written in English (US).
All source files are saved in the content directory. Each section has a directory within that, with each page being represented by a single markdown file.
To edit or create a new page you will need to:
content directory to make your changes - either editing an existing markdown page or creating a new oneIf you have never used git or GitHub before, that may sound daunting, but let's break it down:
Create a "clone" or "fork" of the Documentation repository:
git clone https://github.com/bookwyrm-social/documentation.git
To make changes:
content directory and commit your changes:git commitAt this point you might want to see what your changes will look like when published. See Building docs locally below for instruction on how to preview your changes.
Once you have completed your changes, make a pull request to the docs repository.
Your pull request will be reviewed and one of three things will happen:
If you are asked to make changes, you can make them locally and push your local changes to your fork/clone on GitHub. This will automatically flow through to your pull request. Let the reviewer know when you have completed your updates so they can do another review and hopefully "pull" your changes.
We welcome all contributions. It would be unusual for a contribution to the docs to be rejected immediately. This would only happen if your pull request introduces information that is wrong or misleading with no chance of being improved, or if it has been declared out of scope.
When your pull request is merged, the documentation is automatically updated. You may need to refresh your browser or use "incognito mode" to see the changes in your browser.
If you are adding a new page, you will need to add some metadata and may need to adjust other pages.
At the top of each markdown file is the "frontmatter" in toml format:
Title: Documentation
Date: 2025-04-09
Order: 4
This example shows that the page is called "Documentation", should be the fourth page within its section (in this case, Contributing), and that it was last updated on 9 April 2025. If you add a page anywhere other than at the end of a section, you will need to adjust the order of every page that appears below your new page.
This section is contained within a pair of triple dashes (---). In markdown, triple dashes can also be used to indicate a horizontal rule, however the BookWyrm docs parser can get confused by this. If you need a horizontal rule, enter it as HTML code directly with blank lines above and below:
<hr/>
You might want to see what your changes will look like before sending a pull request. The docs repository includes a development script like the main code repository, with the same name: bw-dev. You can use this to test what your changes will look like.
Unlike the main project, the documentation does not run in a Docker container. If you want to compile the documentation site locally you will need to install the dependencies, and it is recommended that you use a virtual environment:
python -m venv /path/to/new/virtual/environment
source <venv>/bin/activate
pip install -r requirements.txt
There are a number of commands available by running ./bw-dev <command>. The ones you are likely to want to use are:
This will compile markdown files into html files using the generate.py script.
When you run site:compile it will generate a large number of files in the site directory. Do not check these in or include them in your pull request: they will be re-generated on the documentation server when your pull request is merged.
This runs a local web server at http://[::1]:8080/ so you can see what the docs will look like.
This will run black to lint your files and avoid any issues with our automated checks. You are unlikely to need this if you are simply updating the documentation source files in content.
Keep translations aligned by regularly updating from Crowdin:
pull both main and l10n_main so they are up to date in your local repositorymain (e.g. called update_locales) and check it outl10n_main's locale directory into your fork: git checkout l10n_main -- localemainLocales for the language dropdown are listed in i18n.py. Generally we wait for a language to have 70% coverage in Crowdin before adding it to the list to avoid too much content remaining untranslated.
When a new version of BookWyrm is released we need to create a new version of the docs:
v0.8.0.generate.py in the main branch of the docsCheck out every other version in turn, and merge the updated generation file into it so they all have the new branch listed: git checkout main generate.py. Then commit this change, create a PR to merge this change into the version's branch in the docs, and merge it. This will ensure that all pages in all versions of the docs have every other version listed in the dropdown menu.
Merge the change in the main branch last - only merges into main trigger the GitHub action to deploy to the docs web server so if you do this first, the changes in other branches will have no effect.