Skip to main content

For developers

This documentation website was built using Docusaurus. While other pages were written for documentation writers, this page is meant for developers of this documentation website. This guide explains how to install dependencies, run the development server, and debug common issues.

Project structure​

  • docs/category: contains documentation pages sorted by category.
  • src/: contains React components and custom pages (like the home page)
  • static/: contains static assets (images, files)
  • docusaurus.config.js: contains site configuration (navigation bar, footer)
  • sidebars.js: used for sidebar structure.

Prerequisites​

Make sure you have installed:

  • Node.js
  • Yarn package manager (other package managers may also work, but Yarn was used by the developers for this project)

You can check the package versions by executing the following commands in a terminal:

node -v
yarn -v

Site development​

Install dependencies​

From the project root, execute:

yarn install

This installs everything listed in package.json.

Start the development server​

Run the development server:

cd documentation-footloose
yarn start

The cd command changes the directory you're working with. In order to work with the Footloose documentation site, you'll need to navigate the terminal there.

The yarn start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.

When you edit Markdown documents while running the development server, the site reloads automatically and displays your changes.

Build for production​

To build the site for production:

yarn build

This creates a static build in the build/ directory.

To preview the production build:

yarn serve

Common issues and fixes​

Broken dependencies​

You can identify broken dependencies by random crashes or build failures. If starting the development server returns an error message starting with Panic occurred at runtime, executing these steps will usually also fix the issue.

Fix:

  • Delete node_modules and yarn.lock
  • Clean cache via yarn cache clean
  • Reinstall dependencies via yarn install

Development server won't start​

Check if:

  • The port is already in use. If this is the case, kill the other processes.
  • There is a Node version mismatch. If this is the case, update your Node version to a compatible one.
  • If there is a dependency issue as described in Broken dependencies