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 https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter for Docusaurus supported fields. 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 at https://riverscapes.github.io/riverscapes-docusaurus-theme/