Skip to main content

Understanding repo layout

The purpose of this page is to describe the function of each file in this repo.

🗂️ .github folder​

See folder structure
.github
├── ISSUE_TEMPLATE
│   └── bug_report.md
├── pull_request_template.md
└── workflows
    ├── build.yml
    ├── case.yml
    ├── lint.yml
    ├── pages-deploy.yaml
    └── release.yaml
3 directories, 7 files

📂 ISSUE_TEMPLATE​

Contains the bug report template when opening an Issue on GitHub. This can be customized to your needs. Note that by GitHub convention, this name cannot be changed.

📄 pull_request_template.md​

Pull request template when pull request is opened. This can be customized to your needs. Note that by GitHub convention, this name cannot be changed.

📂 workflows​

Contains all the GitHub Actions for the repo.

📄 build.yml​

Build the docs as it would in production to check for any build errors.

📄 case.yml​

Ensure that all markdown files have names which are only lower case letters, digits, dashes or underscores.

📄 lint.yml​

Run npm run lint from package.json. It includes spell checking, TypeScript linting, and CSS styling.

📄 pages-deploy.yaml​

Build and deploy the docs to GitHub Pages when any commit is made to the main branch.

📄 release.yaml​

Check all recent commits made to main branch and automatically cut a release in line with semantic versioning. The Action will read the configuration in .releaserc.js in the root directory of this repo.

🗂️ .husky folder​

tip

Husky manages Git hooks in an easy way and it is used in this repository for pre-commit, commit message, and staged linting so far.

See folder structure
.husky
├── _
│   └── husky.sh
├── commit-msg
├── pre-commit
└── prepare-commit-msg

2 directories, 4 files

📄 commit-msg​

On any commit message, commitlint will be run to ensure that it is compliant. The config used in this repo is the config-conventional found here. This is specified in the package.json on the commitlint JSON key.

📄 pre-commit​

Before a commit, lint-staged will be run which will check all staged files for spelling errors, TypeScript linting, and CSS linting. Settings for it can be found in package.json under lint-staged JSON key.

📄 prepare-commit-msg​

Commit message will use git-cz, which has its settings in package.json under config JSON key. It uses cz-conventional-changelog which is the conventional log standard.

🗂️ blog folder​

tip

Contains all the Markdown and related files for the blog functionality of Docusaurus.

🗂️ docs folder​

tip

Contains all the Markdown and related files for the docs functionality of Docusaurus.

🗂️ src folder​

tip

Contains all the JSX and CSS files for pages functionality of Docusaurus.

See folder structure
src
├── components
│   └── HomepageFeatures
│       ├── index.tsx
│       └── styles.module.css
├── css
│   └── custom.css
└── pages
    ├── index.module.css
    ├── index.tsx
    └── markdown-page.md

5 directories, 6 files

📂 components​

Contains JSX components for React.js which should live separately from the pages folder. The pattern should be that JSX components are broken up here with .tsx extensions and accompanying scoped .modules.css. These components can then be imported by files in the pages folder.

📂 css​

Any non-scoped css files should live in this folder.

caution

It is recommended to leave the default custom.css file by itself in this folder and not add any other files. The custom.css file is referred to as the global styles file which applies to the entire docs site.

📂 pages​

Pages are one-off standalone pages which do not have sidebars as default.

Markdown/MDX pages are still supported in this folder and will be rendered with the file name as the path.

Routing is file-based for any .js and .tsx file.

🗂️ static folder​

Any assets which can be directly copied on build output. Usually images, stylesheets, favicons, fonts, etc.

More information: Referencing your static asset.

See folder structure
static
└── img
    ├── docusaurus.png
    ├── favicon.ico
    ├── logo.svg
    ├── logo_dark.svg
    ├── undraw_docusaurus_mountain.svg
    ├── undraw_docusaurus_react.svg
    └── undraw_docusaurus_tree.svg

2 directories, 7 files

📄 .cspell.json​

A spell checker configuration file which is used in linting to check for misspelling in all files.

Configuration JSON file includes basic configuration with ignorePaths for paths/files which should not be checked. Additional dictionaries can be added, either default supported, or additional files, such as the project-words.txt included in this repository.

📄 .editorconfig​

EditorConfig is supported by most IDEs and text editors to provide consistent coding styles for projects through a config specification.

📄 .eslintignore​

ESLint is used by this project since it contains Javascript, Typescript, and React code and lints the code to provide a consistent style for all developers and contributors.

The .eslintignore file are a list of directories for ESLint to ignore when linting.

📄 .eslintrc.js​

Configuration for ESLint and accompanying plugins used by it to parse and lint the code.

📄 .gitignore​

A file containing files and folders for Git to ignore when adding or committing.

📄 .nvmrc​

Contains the Node.js version that we want to use for this project. It requires the installation of nvm. See here for more.

📄 .prettierrc​

It is recommended to use Prettier to format all files. Whatever is not covered in the .editorconfig will be overridden or specified in this Prettier configuration file.

When you git commit on this repo, lint-staged will run npm run format which will run Prettier to format and save those changes.

📄 .releaserc.js​

Semantic Release is used to easily keep track of version changes to documentation. On push to the main branch, the release GitHub Action will take all necessary commits based on their type and increment the version according to semver conventions. However, it is not strictly necessary and can be removed along with its accompanying action if it is not preferred.

📄 .stylelintignore​

StyleLint is used to lint CSS files. This file ignores directories which do not need to be linted.

📄 .stylelintrc.js​

StyleLint configuration for linting.

📄 CHANGELOG.md​

Semantic Release automatically updates the CHANGELOG file with release history and commits appended to each release. It should not be modified manually.

📄 api.mustache​

This repo by default has the plugin docusaurus-plugin-openapi-docs installed to demonstrate how to integrate OpenAPI documentation directly into Docusaurus. The api.mustache file contains the API template for the plugin when generating the Markdown files.

📄 babel.config.js​

This is the Babel configuration which is used by Docusaurus. It should not be modified.

🦖 docusaurus.config.js​

Contains all major Docusaurus configuration which is necessary to configure its behavior.

🔐 package-lock.json​

Used by npm when npm install is used to lock versions and reduce differences between dev environments if this is not committed into the repository. It should not be necessary to edit this file directory.

📦 package.json​

Used by npm containing configuration scripts, dependencies, dev dependencies and other related dependency configurations.

📖 project-words.txt​

Used by CSpell in the .cspell.json configuration file with additional project words that should not be flagged as misspelling when linting.

🦖 sidebars.js​

Separate .js file used by Docusaurus to provide sidebar configuration. It is possible to place this directly into docusaurus.config.js but has been separated for clarity and ease-of-use.

🦖 tsconfig.json​

This project uses Typescript for React. The tsconfig.json contains Typescript compiler options but is not used in compilation of the project and only for editor experience.