Using Docusaurus

The Riverscapes Consortium uses the free and popular Docusaurus software to publish documentation websites. Below you will find information about how to work with Docusaurus, add content and even how to build a new site from scratch.

Create a new page

A new page is written in markdown and should have an .mdx extension, as that allows you to use react components described below (e.g. Youtube video, ToolsWrapper).

Front matter

Front matter is a section at the very top of each file beginning with three dashes and containing key:value pairs. See the official documentation for Docusaurus supported fields that allow you to do things such as:

over-ride the default heading levels shown in the table of contents (toc_min_heading_level and toc_max_heading_level default to 2 and 3 respectively)
add description and keywords that will be placed in meta tags and used by search engines (description, keywords)

Suggested front matter for Riverscapes docs:

---
title: Friendly Page Title
description: A description of the page
sidebar_position: 1
page-status: stub,messy,mature,protected,generated
page-priority: low,medium,high
---

Pages within each section are ordered by the sidebar_position value. Pages without a value are then ordered alphabetically.
page-status and page-priority tags are proposed for internal use and have no impact on how the page is displayed.

YouTube Videos

Use this syntax for individual videos:

<YouTubeEmbed videoId="mfyhjVfECf4" />

And use this for playlists:

<YouTubeEmbed videoId="videoseries?si=ShLyh1OooBaksIn1&amp;list=PLbpi6ZahtOH4sXk8IP-z9gW9oDz5XjQwA" />

ToolsWrapper Component

Use the ToolsWrapper in your .mdx page to display a grid of tool cards. This component is written and maintained in the Riverscapes Docusaurus Theme.

Component props:

sectionTitle (optional): Adds a heading above the card grid, e.g., sectionTitle="Featured Tools".
cardsize (optional): Sets the card size; can be "sm", "md", or "lg". If not mentioned, the default is "md".

Available fields for each card:

title (required): The main heading for the card.
description (optional): Brief summary or details about the tool.
logoUrl (optional): Path to a small logo displayed on the card.
toolUrl (optional): Link opened when the card is clicked.
imageUrl (optional): Main image shown on the card.
imageLink (optional): Link opened when the image is clicked (overrides card link for the image only).

Here's an example use of the ToolsWrapper:

<ToolsWrapper
  sectionTitle="Example ToolsWrapper Cards"
  cards={[
    {
      title: "Card 1",
      description: "Card with title, description, logo, toolUrl, imageUrl, and imageLink.",
      logoUrl: "/img/logo-md.png",
      toolUrl: "https://example.com/tool",
      imageUrl: "/img/card-image.jpg",
      imageLink: "/img/card-image.jpg",
    },
    {
      title: "Card 2",
      description: "Second card with title, description, logo, toolUrl, imageUrl, and imageLink.",
      logoUrl: "/img/logo-md.png",
      toolUrl: "https://example.com/tool",
      imageUrl: "/img/card-image.jpg",
      imageLink: "/img/card-image.jpg",
    },
    {
    title: "Card 3",
    description: "Card with title, description, logo, toolUrl, imageUrl, and imageLink.",
    logoUrl: "/img/logo-md.png",
    toolUrl: "[https://example.com/tool](https://example.com/tool)",
    imageUrl: "/img/card-image.jpg",
    imageLink: "/img/card-image.jpg",
    },
  ]}
/>

Example Tools Wrapper Cards

Card 1

Card with title, description, logo, toolUrl, imageUrl, and imageLink.

Card 2

Card with title, description, logo, toolUrl, imageUrl, and imageLink.

Card 3

Card with title, description, logo, toolUrl, imageUrl, and imageLink.

LogoWrapper Component

Use LogoWrapper in your .mdx page to display a row of logos.

Component props:

logos (required): An array of logo objects to display.
size (optional): Sets logo size; can be "sm", "md", or "lg". If not mentioned, the default is "md".

Available fields for each logo:

imageUrl (required): Path to the logo image.
name (optional): Name or label shown below the logo.
url (optional): Link opened when the logo is clicked (opens in a new tab).

Here's an example use of the LogoWrapper

<LogoWrapper
  size="sm"
  logos={[
    {
      imageUrl: "/img/logo1.png",
      name: "Logo One",
      url: "https://example.com/one"
    },
    {
      imageUrl: "/img/logo2.png",
      name: "Logo Two",
      url: "https://example.com/two"
    },
    {
      imageUrl: "/img/logo3.png",
      name: "Logo Three"
    }
  ]}
/>

Logo One

Logo Two

Logo Three

Using the GoogleSlides Component

Use GoogleSlides in your .mdx page to embed a Google Slides presentation.

Component props:

src (required): The embed URL for your Google Slides presentation.
width (optional): Width of the embedded slides in pixels. Default is 960.
height (optional): Height of the embedded slides in pixels. Default is 749.

<GoogleSlides
  src="https://docs.google.com/presentation/d/e/2PACX-1vRvfFoZVdGcOsb9jSfj7TYPOcmn85yTBkvp1Y0fkOtZXlINTDkt_tcYmPr-Z9rGGyaXlsp8984ElPB-/embed?start=true&loop=true&delayms=3000"
  width={800}
  height={600}
/>

Common Theme Repository

The Riverscapes Docusaurus theme is stored in a private GitHub repository and includes a demo site that shows off different examples, as well as an empty template for starting new sites.

Use docusaurus.config.ts to customize the footer. The theme reads themeConfig.footer.links and prepends the items into matching columns.

Column titles provided by the theme

Support & Contact
Connect with Us

Titles must match exactly (including capitalization) to merge into an existing column. If the title doesn’t match, a new column is added.

1. Add a link to an existing column

docusaurus.config.ts

themeConfig: {
  footer: {
    links: [
      {
        // Must match an existing column title to merge
        title: 'Support & Contact',
        items: [
          {
            label: 'Knowledge Base',
            href: 'https://riverscapes.freshdesk.com/support/solutions/153000297758',
          },
        ],
      },
    ],
  },
}

Result: “Knowledge Base” appears at the top of the “Support & Contact” column, followed by the theme’s default links.

2. Create a new column

docusaurus.config.ts

themeConfig: {
  footer: {
    links: [
      {
        title: 'Projects & Data',
        items: [
          { label: 'Riverscapes Data Portal', href: 'https://data.riverscapes.net/' },
          { label: 'BRAT Overview', href: 'https://www.riverscapes.net/documentation/brat' },
        ],
      },
    ],
  },
}

Result: A new “Projects & Data” column is appended after the default columns.

3. Multiple columns at once

docusaurus.config.ts

themeConfig: {
  footer: {
    links: [
      {
        title: 'Support & Contact',
        items: [
          { label: 'Knowledge Base', href: 'https://riverscapes.freshdesk.com/support/solutions/153000297758' },
          { label: 'Email Support', href: 'mailto:support@riverscapes.freshdesk.com' },
        ],
      },
      {
        title: 'Community',
        items: [
          { label: 'Forum', href: 'https://www.riverscapes.net/topics?category_id=6901' },
          { label: 'Announcements', href: 'https://www.riverscapes.net/topics/34422/feed' },
        ],
      },
    ],
  },
}

Documentation Workflow

There are different approaches to creating or editing documentation in one of our Docusaurus sites depending on the site, the nature of the change, and your role within the Riverscapes GitHub project.

For small edits (e.g. fixing typos, adding a few sentences, etc.), 'in-place' editing of a file on the main branch using GitHub web UI may be appropriate. For anything more substantial, you should use a development environment that provides allows you to preview how the changes will look, and check for errors using tools such as MarkdownLint and spell check.

In-browser with GitHub

From the bottom of any page is a link to "Edit this page" which takes you to the source document in GitHub. There, if you have permission to the repository, you will see a pencil icon allowing you to edit in place. Make your changes and then commit them, all within a web browser session. No desktop software is needed.

Forking, Branches, pull requests and approvals

For larger changes, or if you don't have permission to the live branch or repository you may need to Fork the repository or create a branch then submit a pull request to have your changes integrated.

Build and preview documentation in a development environment

One way to do this is with codespaces. Or you can clone the repository to your local computer.

To start the local development server

You will need yarn, which in turn requires Node.js. Once installed, run these commands in your terminal of choice.

yarn install
yarn start

🔍 View Your Site

Once the dev server is running, visit

http://localhost:3000

This will display your live documentation site with hot reloading enabled.

Build a New Docusaurus Site from Scratch

This guide walks through creating a new Riverscapes documentation site from the ground up, using macOS as the base system.

Step 1. Start with an Empty Folder

Create a new directory for your site and open it in Visual Studio Code.

mkdir riverscapes-mynewsite
cd riverscapes-mynewsite
code .

Step 2. Clone the Riverscapes Theme Monorepo

Clone the Riverscapes Docusaurus Theme repository. It includes a folder that contains a completely clean template site, with all the files you need to get started.

git clone git@github.com:Riverscapes/riverscapes-docusaurus-theme.git

Open DocusaurusDeveloper.code-workspace. You’ll see the following structure. Note that the Clean Template Site is an alias for the folder sites\template folder on disk.

riverscapes-docusaurus-theme/
│   ├── Docusaurus Theme
│   ├── Developer Site
│   └── Clean Template Site

Step 3. Copy everything from the Clean Template site into your new folder.

Copy the clean template site into your new folder. This gives you a complete starter Docusaurus setup following Riverscapes conventions.

Step 4. Use the Standard Node Version (via NVM).

The Clean Template includes a .nvmrc file that pins the correct Node version. From your new site folder, simply run:

nvm use

Step 5. Install Dependencies

From inside your new project folder, install all dependencies:

yarn install
yarn add loglevel

This installs Docusaurus, the Riverscapes Theme, and other required packages defined in the Clean Template’s package.json.

Step 6. Update Site Configuration

Open docusaurus.config.ts file and update the key details to match your new site:

export default {
  title: 'My New Riverscapes Site',
  url: 'https://riverscapes.github.io',
  baseUrl: '/mynewsite/',
  organizationName: 'Riverscapes',
  projectName: 'mynewsite',
  favicon: 'img/favicon.ico',

  themeConfig: {
    navbar: {
      title: 'My New Site',
      items: [{ to: '/docs/intro', label: 'Docs', position: 'left' }],
    },
    footer: {
      copyright: `Copyright © ${new Date().getFullYear()} Riverscapes Consortium`,
    },
  },
};

💡 The baseUrl should match your GitHub repository name — this determines the deployed site path (e.g., /mynewsite/).

Step 7. Run the Dev Server

Start your new site locally:

yarn start

Then open your browser to http://localhost:3000. You should see your new site running with the Riverscapes theme applied.

Step 8. GitHub actions

The template site includes a folder called .github that should be placed in ROOT of the new site repository. Make sure that the repo where you are publishing the site has github pages enabled and published from the appropriate branch (typically either main or docs). Pushing changes on the appropriate branch will automatically publish the site.

Create a new page

Front matter

YouTube Videos

ToolsWrapper Component

Example Tools Wrapper Cards

Card 1

Card 2

Card 3

LogoWrapper Component

Using the GoogleSlides Component

Common Theme Repository

Customizing the Footer

Column titles provided by the theme

1. Add a link to an existing column

2. Create a new column

3. Multiple columns at once

Documentation Workflow

In-browser with GitHub

Forking, Branches, pull requests and approvals

Build and preview documentation in a development environment

To start the local development server

Build a New Docusaurus Site from Scratch

Step 1. Start with an Empty Folder

Step 2. Clone the Riverscapes Theme Monorepo

Step 3. Copy everything from the Clean Template site into your new folder.

Step 4. Use the Standard Node Version (via NVM).

Step 5. Install Dependencies

Step 6. Update Site Configuration

Step 7. Run the Dev Server

Step 8. GitHub actions