Skip to content

Buddies of Budgie documentation, built with Docusaurus.

License

Notifications You must be signed in to change notification settings

BuddiesOfBudgie/docs

Repository files navigation

Buddies of Budgie Documentation

Buddies of Budgie Documentation is our documentation center leveraging Docusaurus.

Getting Started

To get started developing our Docusaurus instance, or writing documentation, first fork this project in order to submit pull requests for your changes

This project is written using TypeScript and React, with some documentation being Markdown or MDX. To facilitate development, we use nvm and Yarn.

NVM

To set up nvm, the Node Version Manager, follow the instructions listed here. We recommend setting up their shell integration as well, so you can automatically switch to the correct Node version when working on this project. Otherwise, ensure you run nvm use. This project requires the "current" supported release series of Node.

You can validate you are using the latest by running node --version. Your version should be at least 19.x.

Yarn

This project makes use of Yarn for its package management. After setting up nvm and ensuring you are running the latest Node, run:

corepack enable

Installing Dependencies

To install the required dependencies, run: yarn

Starting Docusaurus

To start the live reloading Docusaurus, run: yarn start

Other Useful Commands

  • Clear local build cache: yarn clear
  • Linting: yarn lint
  • Updating translation files: yarn write-translations
  • Validate build: yarn build

Containers Images

We provide the following targets for our container image:

  • development: This can be used to facilitate local development should you not wish to set up a host-based local development environment.

Using development target for local development

While you can run the development target without specifying a volume, which would effectively be a copy of what you have in your working directory at image build time, there is no advantage to doing so over running the deploy target. So this section will focus on use with our working directory set as mounted volume.

For this section, we will be using podman, although the commands should be identical for docker as well should you use that instead. Just swap podman for docker.

  • Build the image: podman build -t docusaurus:development --target development .
  • Run the image: podman run -it --rm -p 3000:3000 -v .:/app docusaurus:development
  • Interactive with sh as entrypoint (does not automatically start docusaurus): podman run -it --rm -p 3000:3000 --entrypoint /bin/sh --tty -v .:/app docusaurus:development

This will mount the working directory at /app as a volume and whenever there is a change to this directory, Docusaurus will automatically rebuild thanks to hot module reloading.

License