Skip to main content

Docusaurus Template

Introduction​

Docusaurus is a tool for easily building and maintaining documentation websites. We've adapted a Docusaurus template so teams can get started quickly and securely. This template is designed to help you:

  • Create professional documentation sites
  • Deploy your site easily
  • Stay aligned with company security and styling standards.

alt text

For a deeper dive into Docusaurus, read Docusaurus tutorial !

Key Features of the Template​

  • Security: Built-in security checks.
  • Authentication: Microsoft Authentication (MSAL) for secure access control.
  • Automated Deployment: Preconfigured workflows with GitHub Actions.
  • Custom Design: Styled to match company branding.
  • Search Functionality: Integrated search for easy navigation.
  • Environment Variables: dotenv support for flexible configuration.
  • Linting and Code Quality: Tools for maintaining clean, consistent code.

How to Use the Template​

Using this templated includes these main steps:

  • Request a Fork - contact the Engineering team to create a repository fork for your project.
  • Choose your preferred working environment:
    • Option 1 - Clone the Repository Created in Step 1 - Install the site locally. Note: local Admin privileges are needed to be able install dependencies needed for Docusaurus
    • Option 2 - Work directly in the GitHub web-based editor / GitHub Codespaces. It can be done by pressing . in the Repository Created in Step 1
  • Add content - create folders & pages for your site under /docs folder. The folders created under /docs will be reflected in sidebar menu. Add and edit Markdown files to update content.
  • Push Changes and Deploy - push your changes to trigger automated workflows for deployment.

For more detailed instructions, visit the GitHub wiki.

How to Stay Updated With Template Changes​

To ensure your fork has the latest changes from the base repository:

  1. Navigate to your GitHub profile and open your forked repository.
  2. In the Code tab, look for the Sync fork button.
    • If your fork is up to date, you'll see the message: This branch is not behind the upstream.
    • If your fork is out of date, you'll see: This branch is out-of-date. Click the Update branch button to fetch and merge the latest changes.

Recommendation:​

To avoid directly modifying the main branch:

  1. Create a new branch (e.g., fork-merge) and apply the updates there.
  2. Always verify that your changes are compatible with the updates from the parent repository before syncing.
  3. If your fork has conflicting changes, GitHub will notify you during the sync process. You can resolve conflicts using the web interface or locally.
  4. Once the changes are reviewed, create a Pull Request to merge the updates into the main branch.
  5. Avoid using the Compare & Pull Request suggestion directly from GitHub. Instead, go to Pull requests > New pull request to ensure you are merging changes into the correct repository.

More details can be read here

Best Practices of Usage​

Here’s a guide with best practices for using a Docusaurus template to fork the repository and write documentation effectively:

1. Fork the Repository​

  • Always start by forking this repository to your GitHub account. This allows you to customize and maintain your documentation independently.

2. Organize Your Content​

  • Use Clear Folder Structures: Organize markdown (.md) files into folders that reflect the hierarchy of your documentation. For example: 
    docs/
      getting-started.md
      setup/
        installation.md
        configuration.md
      features/
        feature1.md
        feature2.md
  • Keep Files Small and Focused: Each .md file should focus on a single topic or section to make content easy to find and maintain.

3. Follow Markdown Standards​

  • Use proper Markdown syntax for headings, lists, tables, and code blocks.
  • Include descriptive headings and subheadings to make the content skimmable.
  • Add code examples where applicable, using fenced code blocks for syntax highlighting: 
    ```bash
    npm install
  • Include hyperlinks to related sections or external resources for better navigation.

4. Preview Locally Before Committing​

  • Run the Docusaurus development server to preview your changes: 
    npm install
    npm start
  • Check for broken links, formatting issues, and navigation correctness.

5. Include Media and Assets​

  • Store images, videos, or other assets in the /static directory, organized by topic. 
    static/
      images/
        setup-guide.png
        feature-demo.gif
  • Reference assets using relative paths: 
    ![Setup Guide](../static/images/setup-guide.png)

6. Keep Documentation Up to Date​

  • Regularly review your content for outdated information.
  • Highlight new features or updates prominently in a "What's New" section or changelog.

By following these best practices, you can ensure your forked Docusaurus project is well-structured, user-friendly, and easy to maintain!

Support Contact​

If you want to use the template and need further support, please contact the Software Engineering Team.