Forem Creators and Builders

loading...
Forem Core Team

Changelog: developers.forem.com — New Home of Developer Docs

Andy Zhao
allo
・2 min read

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
Enter fullscreen mode Exit fullscreen mode

Local Development

Once installed:

yarn start
Enter fullscreen mode Exit fullscreen mode

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:

  1. edit some Markdown
  2. make a pull request
  3. preview it through a Netlify deploy preview
  4. 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!

Discussion (2)

Collapse
amorpheuz profile image
Yash Dave

New docs site and that too on Docusaurus?! Awesome <3

Collapse
andy profile image
Andy Zhao Author

Indeed! It's been a pretty great tool to use :)