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/forem-docs.
Forem Developer Docs
Welcome to Forem's developer documentation! The docs are built using Docusaurus 2, a React and Markdown based documentation website generator.
Technical Overview
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
Installation
git clone https://github.com/forem/forem-docs.git
yarn install
Local Development
Once installed:
yarn start
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!
Top comments (2)
New docs site and that too on Docusaurus?! Awesome <3
Indeed! It's been a pretty great tool to use :)