NetFoundry Docusaurus Shared

This repository is for shared documentation styles, components and the like. NetFoundry has chosen to use Docusaurus as the Jamstack provider for documentation. Docusaurus provides reusable components and theming centered around a React core.

Prerequisites

You'll need npm installed and yarn. npm is installed by package manager (or however you want). yarn is installed by running npm add -g yarn.

Getting Started

To get started, clone this repo or download the bootstrap.sh file and execute it. It will ask you for a location to put the resultant files into.

Best Practices

CSS

There's a shared stylesheet that needs to be linked and used. As of July 2025 it needs to be clarified as it's grown crufty over the years. Styling should be done with caution since it should be universal and will affect all docs sites. The bootstrapper updates the generated src/css/custom.css and appends the shared css at the top using 'import'.

The source of the css will come from the css folder in the shared project.

Relative Linking

At this time, it's considered the best practice to use fully qualified links everywhere. Many IDEs will be able to resolve these paths and help when documentation needs to be rearranged. Docusaurus definitely works best when using a fully qualified link. DO not use the @site alias and do not use an absolute path such as one starting with /.

Example, do this:

Here [is a link](../to/some/path.md)

NOT THIS:

Here [is a link](@site/to/some/path)
Here [is a link](/docs/to/some/path.md)

Images Go in the Static Folder

Add images to the static folder located at the project root but make sure images are scoped to your site, not placed at the root. The root will be reserved for shared images that all are expected to use. Anything at the root may be replaced when deployed to the live docs site.

Example, put images here:

/tmp/my-doc-site/static/img/my-doc-site

NOT here:

/tmp/my-doc-site/static/img/

Use Partials Sparingly

It's tempting to add the same content over and over again in multiple places but this is not always best for readers. Docusaurus supports using partials, or markdown files that start with _ to indicate these are not meant to be included in the final site, but can be referenced in other markdown.

Example:

import SharedContent from '../_shared.content.md'

<SharedContent />

Generated Theme Layout

A Docusaurus Layout is generated by the bootstrap.sh. Don't change this theme component. Ideally, you won't even know it's there. If it's an opensource project and you want to ask for GitHub stars update the Layout and add starProps. For example:

<NetFoundryLayout
    starProps={{ label: "Like what you see? Give us a star on GitHub",
               repoUrl: 'https://github.com/openziti/ziti' }}>