Skip to main content

Docusaurus

This is a highly opinionated take on how to configure and organize Docusaurus to help document the ins and outs of your application. There are many more features and settings that this guide does not utilize. You can read more about them in the Docusaurus Documentation

Installation​

tip

Review the official Docusaurus Installation Instructions for changes.

Run the following command:

pnpx create-docusaurus@latest docusaurus classic
info

Docusaurus installs in a sub directory as a separate application with it's own package.json defining dependencies and scripts. It may be better to organize your repo as a monorepo; where your application files are located within it's own sub directory. You may also consider using tools like NX or Turborepo to manage task orchestration at the CI/CD layer. This is particularly useful to run ESLint and Prettier scripts using a single command from a single directory.

Cleanup​

cd docusaurus and do the following:

  • Delete the README.md file
  • Delete the ./blog and ./src directories
  • Keep the ./docs directory but delete it's contents
  • Inside ./static/img keep or replace the ./static/img/favicon.ico and ./static/img/logo.svg files and delete everything else

Docusaurus Config​

Update ./docusaurus.confg.ts configuration:

docusaurus.confg.ts
const config: Config = {
  title: "🟡 YOUR TITLE HERE",
  tagline: "🟡 YOUR TAGLINE HERE HERE",
  favicon: "img/favicon.ico",
  url: "https://🟡YOUR-DOCUSAURUS-PRODUCTION-URL-HERE",
  baseUrl: "/",

  // 🟡 Delete these 2 properties if you're not deploying to GitHub pages
  organizationName: "🟡 GITHUB ORG/USER NAME",
  projectName: "🟡 YOUR REPO NAME",

  onBrokenLinks: "throw",
  onBrokenAnchors: "warn",
  onBrokenMarkdownLinks: "warn",
  onDuplicateRoutes: "warn",

  presets: [
    [
      "classic",
      {
        docs: {
          routeBasePath: "/",
          sidebarPath: "./sidebars.ts",
          // 🟡 `showLastUpdateTime` requires access to git history during the
          // build. It will not work correctly with shallow clones (a common
          // default for CI systems)
          showLastUpdateTime: true,
          // 🟡 The value for `editUrl` follows the url pattern for GitHub repos. Other repos may differ
          editUrl: "🟡 <YOUR REPO URL>/blob/main/docusaurus",
        },
        blog: false,
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    navbar: {
      title: "🟡 YOUR DOCUMENTATION TITLE",
      logo: {
        alt: "🟡 YOUR ALT TEXT",
        src: "img/logo.svg",
      },
      items: [
        {
          href: "🟡 YOUR PROJECT REPO URL",
          label: "🟡 Azure DevOps | GitHub | Bitbucket | Other",
          position: "right",
        },
      ],
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  } satisfies Preset.ThemeConfig,
};

Update sidebars.ts configuration:

sidebars.ts
// Sidebar Documentation: https://docusaurus.io/docs/sidebar
const sidebars: SidebarsConfig = {
  mainSidebar: [
    {
      type: "autogenerated",
      dirName: ".", // '.' means the current docs folder
    },
  ],
};

Add Initial Project Documentation​

README.md​

Replace the contents of the repositories README.md file with one of the following:

README.md
# 🟡 TODO: Project Heading

## About this Project

### Description

🟡 TODO: Project Description Here

### Project Framework

This project was created using the Next.js framework. To learn more about Next.js, take a look at the following resources:

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

## Getting Started

### Step 0 - Prerequisites

- [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Install Node 24.0+](https://nodejs.org/en/download)
- [Install PNPM](https://pnpm.io/installation#on-windows)

### Step 1 - Install Dependencies

Run the following command:

```terminal
pnpm install
```

### Step 2 - Run Development Server

```terminal
pnpm dev
```

## Additional Documentation

More documentation about the tools, conventions, organization, and deployment infrastructure of this application can be found at [🟡 TODO: link to published docusaurus website](#additional-documentation)

index.mdx​

Create a docusaurus/docs/index.mdx file and add the following:

docusaurus/docs/index.mdx
---
title: ""
sidebar_label: "Introduction"
sidebar_position: 0
---

import Readme from "../../README.md";

<Readme />

01-scripts.md​

Create a docusaurus/docs/01-scripts.md file and add one of the following:

docusaurus/docs/01-scripts.md
# Scripts

| Script       | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `pnpm dev`   | Starts Next.js in development mode with Hot Module Reloading, error reporting, and more.            |
| `pnpm build` | Creates an optimized production build of your application, displaying information about each route. |
| `pnpm start` | Starts Next.js in production mode. The application should be compiled with `pnpm build` first.      |
| `pnpm lint`  | Runs ESLint for all files in the `/src`, `/app`, `/pages`, `/components`, and `/lib` directories.   |

02-code-quality​

Create a docusaurus/docs/02-code-quality directory and add the following:

02-code-quality/_category_.json​

docusaurus/docs/02-code-quality/_category_.json
{
  "label": "Code Quality"
}

03-libraries-tools​

Create a docusaurus/docs/03-libraries-tools directory and add the following:

03-libraries-tools/_category_.json​

docusaurus/docs/03-libraries-tools/_category_.json
{
  "label": "Libraries & Tools"
}

03-libraries-tools/99-docusaurus.md​

docusaurus/docs/03-libraries-tools/99-docusaurus.md
# Docusaurus

## Quick Start

Docusaurus is effectively a second application within our repo, with its own `package.json`. To start Docusaurus locally, run the following commands:

```terminal
cd docusaurus
pnpm install
pnpm start
```

## Why Documentation Should Live in the Repository

Documentation should live in the repository to ensure it stays close to the code it describes. This approach provides several benefits:

1. **Version Control**: Documentation evolves alongside the codebase, ensuring it remains accurate and up-to-date. Changes to the code and documentation can be reviewed together in pull requests.
2. **Collaboration**: Developers can contribute to both the code and its documentation in the same workflow, fostering a culture of maintaining high-quality documentation.
3. **Discoverability**: Keeping documentation in the repository makes it easier for developers to find and reference it while working on the code.
4. **Consistency**: By integrating documentation into the same repository, it becomes easier to enforce standards and ensure consistency across the project.
5. **Automation**: Tools like Docusaurus can automatically generate and deploy documentation from the repository, streamlining the process and reducing manual effort.

## What is Docusaurus

The documentation you're reading now was written and deployed using [Docusaurus](https://docusaurus.io/docs). Docusaurus is an open-source framework designed to help developers build, deploy, and maintain documentation websites efficiently. Documentation can be written in markdown or mdx files and Docusaurus will generate a static website that is organized based on folder structure and file names.

Docusaurus is incredibly feature rich. It is worth it to glance through the [Docusaurus Documentation](https://docusaurus.io/docs) to get an idea as to what is possible.

## Scripts

:::tip
For more details see [Docusaurus CLI Documentation](https://docusaurus.io/docs/cli)
:::

| Script                    | Description                                                               |
| ------------------------- | ------------------------------------------------------------------------- |
| `pnpm docusaurus`         | Alias for running the Docusaurus CLI                                      |
| `pnpm start`              | Builds and serves a preview of your site locally with Webpack Dev Server. |
| `pnpm build`              | Compiles your site for production.                                        |
| `pnpm swizzle`            | Swizzle a theme component to customize it.                                |
| `pnpm deploy`             | Deploys your site with GitHub Pages.                                      |
| `pnpm clear`              | Clear a Docusaurus site's generated assets, caches, build artifacts.      |
| `pnpm serve`              | Serve your built website locally.                                         |
| `pnpm write-translations` | Write the JSON translation files that you will have to translate.         |
| `pnpm write-heading-ids`  | Add explicit heading IDs to the Markdown documents of your site.          |
| `pnpm typecheck`          | Checks for TypeScript type errors to ensure type safety.                  |

## Notable Features

- Most of the features this documentation site uses comes from the [Docs Guide](https://docusaurus.io/docs/docs-introduction) and [Markdown Features Guide](https://docusaurus.io/docs/markdown-features).
- These docs use autogenerated sidebar feature. The names of sidebar items are based on file names. This can me modified using `_category_.json` files. [Read more here](https://docusaurus.io/docs/sidebar/autogenerated#category-item-metadata)
- An understanding of the [Docusaurus configuration file](https://docusaurus.io/docs/configuration) may also be beneficial

## Usage with Prettier

- Prettier might auto-format code to invalid syntax when also using Docusaurus [admonition](https://docusaurus.io/docs/markdown-features/admonitions) feature. Read [Usage with Prettier Documentation](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier) to learn how to correct for this.
- Prettier supports only the legacy MDX v1. If you get an unintentional formatting result, you may want to add `{/* prettier-ignore */}` before the problematic area, or add `*.mdx` to your `.prettierignore`, until Prettier has proper support for MDX v3. [One of the main authors of MDX recommends remark-cli with remark-mdx](https://github.com/orgs/mdx-js/discussions/2067).

## Useful VS Code Setting

VS Code automatically sets some Markdown-specific settings behind the scenes that override general user settings, such as the `"editor.wordWrap": "on"` setting. If you'd like `.mdx` to wordwrap as well add the following to your VS Code settings file:

```json
{
  // . . .
  "[mdx]": {
    "editor.wordWrap": "on"
  }
}
```

04-ci-cd​

Create a docusaurus/docs/04-ci-cd directory and add the following:

04-ci-cd/_category_.json​

docusaurus/docs/04-ci-cd/_category_.json
{
  "label": "CI/CD"
}

98-vs-code​

Create a docusaurus/docs/98-vs-code directory and add the following files:

98-vs-code/_category_.json​

docusaurus/docs/98-vs-code/_category_.json
{
  "label": "VS Code"
}

98-vs-code/01-vs-code-settings.md​

docusaurus/docs/98-vs-code/01-vs-code-settings.md
# VS Code Settings

VS Code stores workspace settings at the root of the project in a `.vscode/settings.json` file. This makes it easy to share settings with others in a project. Workspace settings are specific to a project and override user settings.

98-vs-code/02-vs-code-extensions.md​

docusaurus/docs/98-vs-code/02-vs-code-extensions.md
# VS Code Extensions

:::note
Some of the extensions listed below have also been added to the workspace recommended extensions file: `.vscode/extensions.json`
:::

| Extension Name                                                                                                 | Description                                                                                                                                                                                                                                                                                             |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph)                            | View a Git Graph of your repository, and easily perform Git actions from the graph.                                                                                                                                                                                                                     |
| [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat)                 | An AI pair programmer tool that helps you write code faster and smarter.                                                                                                                                                                                                                                |
| [GitHub Markdown Preview](https://marketplace.visualstudio.com/items?itemName=bierner.github-markdown-preview) | Changes VS Code's built-in markdown preview to match GitHub markdown rendering in style and content.                                                                                                                                                                                                    |
| [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)             | Linting for markdown files to encourage standards and consistency for Markdown files.                                                                                                                                                                                                                   |
| [MDX for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)         | Adds language support for MDX                                                                                                                                                                                                                                                                           |
| [open in browser](https://marketplace.visualstudio.com/items?itemName=techer.open-in-browser)                  | Useful to quickly open test coverage files in browser.                                                                                                                                                                                                                                                  |
| [Better Comments](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments)              | The Better Comments extension will help you create more human-friendly comments in your code. With this extension, you will be able to categorise your annotations into `Alerts`, `Queries`, `TODOs`, `Highlights`,`Commented out code can also be styled to make it clear the code shouldn't be there` |

99-articles​

99-articles/_category_.json​

docusaurus/docs/99-articles/_category_.json
{
  "label": "Articles"
}