Skip to main content

Documentation Maintenance

This website is built using Docusaurus. In addition, Bun is used for package management and runtime. Thus, it is required that you have Bun installed in order to continue.

Setup​

Step 1 - Clone the documentation repository​

Clone this repository directly using Git.

git clone https://github.com/UCMercedACM/chapter-docs

Step 2 - Install dependencies and tooling​

warning

Bun must be installed for this step and others

Within the freshly cloned repository, install the tooling and dependencies that is required

bun install

Step 3 - Run the development server​

By using bun start, we can start the development server, which will be helpful to write, and view changes

bun start

Details​

MDX for Markdown​

MDX allows us to integrate JSX components directly to our Markdown content. All documentation content are in MDX to allow for this to take advantage. Further details of how Docusaurus uses MDX can be found within Docsuarus's documentation. All markdown content found within the docs folder must have the file extension *.mdx.

Structure​

docs/
├── introduction/
│   ├── index.mdx
│   └── ...
└── projects/
    ├── chapter-website/
    │   ├── _category_.json
    │   └── ...
    ├── kanae/
    │   ├── _category_.json
    │   └── ...
    └── index.mdx

Note that ... stands for other Markdown content, just to make it more simpler. New sections, must be a folder within the docs folder. I.e., if an request to include a new section, such as Administrative, then the name of the folder must be of the section in all lowercase. If an subsection needs to be included, please make another folder of the same name of the proposed subsection in lowercase, and include the category metadata through _category_.json. All folders need an file present, which is the index file for each section. The file is the index, i.e. index.mdx.

Code Formatting​

Generally, Markdown content does not need to be linted or formatter, although it is recommended to have the markdownlint VS Code extension installed to find common Markdown errors and others.

For all other logic, which includes the TSX code that is used to build the front page and custom cards, Biome is used instead. Lefthook is used as an Git hooks manager. Lefthook is automatically included and ran during post-installation of installing dependencies.