Edit Documentation

Overview

This documentation is built using Docusaurus. Docusaurus is a static site generator that is used to create documentation websites. It is a modern and flexible tool that allows for easy creation and maintenance of documentation websites.

Structure of the documentation

The documentation is divided into three categories:

docs/
├── Introduction/
├── Components/
└── Development/
    ├── Frontend/
    ├── Backend/
    └── Documentation/

The first category, Introduction, gives an introduction and a tutorial on how to use the Firmware Vault. It should only contain information necessary to show the installation process and teach the usage. Development topics shouldn't be mentioned and components can be mentioned but should be linked to the main chapter in the category "Components".
For example: in the chapter How To Use is shown how the "Data Explorer" is used and what configuration options are available. How it works internally should not be explained here but in the Data Explorer chapter.

The second category, Components, contains all used components in the project, like the Job Dashboard or the Firmware Scraper. Each component should have an own chapter in which it is explained what its task is and how it works.

The third category, Development, contains everything necessary to continue developing the Firmware Vault. The chapters are split in the sub categories Frontend, Backend and Documentation according to its topic.

Create a new documentation page

1. Create a new Markdown file (.md) in the appropriate directory under docs/:

docs/
├── Getting Started/
│   └── your-new-file.md
├── Frontend/
├── Backend/
└── your-new-folder/
    └── your-new-file.md

2. Add the following frontmatter at the top of your Markdown file:

---
id: your-new-file
title: Your New File Title
---

Your content here...

3. Update the sidebars.ts file to include your new page. For example, to add a new page to the "Frontend" category:

{
  type: 'category',
  label: 'Frontend',
  items: [
    'Frontend/introduction',
    'Frontend/your-new-file'  // Add your new file here
  ],
},

For more indepth information on this topic: official docusaurus documentation

Images

1. To add an image, you have to put it in the img folder of the directory where the markdown file is located.

# Example for the root docs folder
docs/
└── img/
    └── your-new-image.png // If the markdown file is located in the root docs folder.

# Example for a specific folder
docs/
└── Frontend/
    └── img/
        └── your-new-image.png // If the markdown file is located in a specific folder.

2. Reference the image in your Markdown file using the following syntax:

![Image Description](img/your-new-image.png)

For more indepth information on this topic: official docusaurus documentation

Navbar new category

1. Add the following to the docusaurus.config.ts file in the themeConfig section. Make sure to add the new category to the items array:

{
  type: 'dropdown',
  label: 'Docs',
  position: 'left',

  items: [
    {
      label: 'Introduction',
      to: '/docs/introduction',
    },
    ...,
    {
      label: 'New Item', // Add the new item here
      to: '/docs/new-item',
    },
  ],
},

For more indepth information on this topic: official docusaurus documentation

Spellchecking

For spellchecking we use the python package codespell. Every commit that changes the documentation automatically gets checked for spelling errors by our git pipeline.

To locally use codespell before committing, simply install the pip package.

Codespell can ignore words and files. To get the current list of ignored files, check out the .gitlab-ci.yml, for ignored words check out the file docs/.codespell.ignore.

To execute codespell, simply change to the documentation folder and use this command:

codespell --ignore-words=.codespell.ignore --skip="*.json,*.ts,*.lock"