We've moved our developer documentation over to developers.forem.com!
This new documentation site is running on Docusaurus, a static site generator based on React and Markdown. This gives us many benefits, such as:
- a reliable and well-maintained docs generator
- a lot of customization in the styling of the docs
- a fairly similar experience in reading and editing pages
We've also moved the docs from being a folder in the main
forem/forem repository to its own repository:
Forem Developer Docs
Welcome to Forem's developer documentation! The docs are built using Docusaurus 2, a React and Markdown based documentation website generator.
Most of the configuration here is not too different from the basic
preset-classic of Docusaurus. The main folders are:
docs: where the documentation lives
src: any custom CSS, components or pages
static/img: any image files
git clone https://github.com/forem/forem-docs.git yarn install
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
All relevant Markdown files are in
docs/. To update any docs, simply update the Markdown file with your favorite Markdown editor
You can also add new files to the relevant sections.
For other types of contributions outside of text changes to Markdown files, please see Docusaurus' docs for additional…
This allows us to keep the main repo with issues and pull requests about the Forem app itself, and all things documentation stay separated in its own repo. Also, a standalone repo will be simpler to pull down locally, and easier to open a GitHub Codespace to start editing. Now contributors won't have to wait for our CI to pass before their pull request can be merged!
In terms of the contribution process, it's pretty much the same:
- edit some Markdown
- make a pull request
- preview it through a Netlify deploy preview
- see it live when it's merged
One point I want to mention is that having a separate repo does move the "contribution context" out a bit. While it's convenient and helpful to have the docs in the same repo as you're working on, we felt that the benefits of having the docs in a separate repo outweigh the downsides here.
We hope that these points outlined above provide an overall easier way to contribute to our documentation. 🙂 And of course, we hope you like the new, shiny website!