Using Docusaurus

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 the 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
---

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

How to embed a Youtube Video

Use this syntax:

Individual Video

<YouTubeEmbed videoId="mfyhjVfECf4" />

Playlists

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

Using the ToolsWrapper Component

Use ToolsWrapper in your .mdx page to display a grid of tool cards.

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).

<ToolsWrapper
  sectionTitle="Example 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 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.

Using the 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).

<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

We have a private GitHub repository for the theme and a demo site.

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.

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.

Create a new page

Front matter

How to embed a Youtube Video

Individual Video

Playlists

Using the ToolsWrapper Component

Example Cards

Card 1

Card 2

Card 3

Using the 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