Version: v0.12.0

Makersaurus Features

Most Docusaurus features are supported in Makersaurus. There are a few custom features as well.

Dependencies

The following packages are included with Makersaurus by default:

emotion
material-ui
material-ui icons

If you don't need some of these packages, it is best to remove them from makersaurus.config.js. The fewer dependencies you have, the faster your project will build and load.

react-player is also installed by default. It powers the global <Video> component, so it's a core dependency that you don't list in makersaurus.config.js and shouldn't remove.

Code highlighting

Code highlighting is enabled via Prism. For example:

function Section({ title, groups }) {
  const id = title.replaceAll(' ', '-').toLowerCase();
  return (
    <section className={styles.sections} id={id}>
      <div className='container'>
        <h2>{title}</h2>
        <div className='row'>{groups && groups.length > 0 && groups.map((props, idx) => <Group {...props} />)}</div>
      </div>
    </section>
  );
}

Code highlighting works better when you include the language used after your backticks. Here is an example of some python code with the language specified:

```py
def BinarySearch(lys, val):
first = 0
last = len(lys)-1
index = -1
while (first <= last) and (index == -1):
    mid = (first+last)//2
    if lys[mid] == val:
        index = mid
    else:
        if val<lys[mid]:
            last = mid -1
        else:
            first = mid +1
return index
```

vs. without the language specified:

```
def BinarySearch(lys, val):
first = 0
last = len(lys)-1
index = -1
while (first <= last) and (index == -1):
    mid = (first+last)//2
    if lys[mid] == val:
        index = mid
    else:
        if val<lys[mid]:
            last = mid -1
        else:
            first = mid +1
return index
```

Injecting text files

You can inject text files in a Makersaurus project by putting them in static/files. To show them on a Markdown page, first add this import at the beginning of the file:

import useBaseUrl from '@docusaurus/useBaseUrl';

Then, add this snippet where you want to inject the text:

<object data={useBaseUrl("files/name-of-file.txt")} width="900" height="200" />

Replace name-of-file.txt with the correct filename and adjust the width and height as needed. The final result should look like this:

Includes Plugin

Disabled: It doesn't support React 18 for now. When it supports the latest React again, we can use it. Issue ticket

The Includes Plugin can be installed by making the following additions to makersaurus.config.js:

{
  ...
  dependencies: {
    ...
    "docusaurus-plugin-includes": "^1.1.4",
  },
  includesPlugin: {
    sharedFolders: [{ source: "../../_shared", target: "../docs/shared" }],
    postBuildDeletedFolders: ["shared"],
    replacements: [
      { key: "{ProductName}", value: "My long product name for XYZ" },
      { key: "{ShortName}", value: "XYZ" },
    ],
  }
}

Afterwards you can inject text in Markdown using the keys you provided in the replacements array. In the example above, {ShortName} will become "XYZ".

You can also inject an entire Markdown file into another file! Use the following syntax: {@include: ./file-to-inject.md}

The following list items demonstrate these features in action:

- ProductName: {ProductName}
- ShortName: {ShortName}
- {@include: ./inject-me.md}

Using the embeds or injectedHtmlTags fields are not supported in Makersaurus - refrain from using these features to keep our docs sites secure and working properly.

Mermaid

To render Mermaid diagrams, turn on mermaid under markdown in makersaurus.config.js:

{
  ...
  markdown: {
    mermaid: true,
  }
}

To turn Mermaid off, remove the mermaid line (or set it to false). When mermaid is on, Makersaurus installs the required theme (@docusaurus/theme-mermaid) and registers it for you, and the diagrams use a readable theme in both light and dark mode. Write diagrams in fenced mermaid code blocks. Here is an example diagram:

Math

To render math equations with KaTeX, turn on math under markdown in makersaurus.config.js:

{
  ...
  markdown: {
    math: true,
  }
}

To turn math off, remove the math line (or set it to false). When math is on, Makersaurus installs the required packages (remark-math, rehype-katex, katex) and bundles the KaTeX style sheet for you, so math renders offline with no CDN.

Write inline math between single dollar signs, and display (block) math between double dollar signs:

The area of a circle is $A = \pi r^2$.

$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$

Redocusaurus

The Redocusaurus plugin can be used by making the following additions to makersaurus.config.js:

You can use a link instead of the file path for the spec. e.g. 'https://document-ai-backend.cloud-qa.h2o.ai/api-doc/ai/h2o/document_ai/business/v1/archive_service.swagger.json'

Examples

makersaurus.config.js

  dependencies: {
    ...
    "redocusaurus": "^2.0.2"
  },
  redocusaurus: {
    specs: [
      {
        id: 'open-api-1',
        spec: "../external_assets/aiem.swagger.json",
        route: "api/open-api-1",
      },
    ],
  },

sidebars.js

    {
      type: 'category',
      label: 'Open APIs',
      items: ['open-apis/open-api-1'],
    },

open-apis/open-api-1.mdx

---
title: Open API 1
hide_table_of_contents: true
---

import ApiDocMdx from '@theme/ApiDocMdx';

The ApiDocMdx `id` is `redocusaurus` spec id in the `docusarus.config.ts`

<ApiDocMdx id='open-api-1' />

You can use any of the Redocusaurus plugin options.

Version custom field

In the Feature Store docs, each version of the documentation is a separate Makersaurus project and a custom field is needed to delineate the active version. You can use the versionCustomField property in makersaurus.config.js to store this value:

versionCustomField: process.env.VERSION,

After restarting Makersaurus, this variable will be available in the site config: siteConfig.customFields.versionCustomField.

Announcement bar

You can add an announcement bar to your project by adding a configuration object to makersaurus.config.js:

announcementBar: {
  id: "deprecation-warning",
  content: "Warning: this software is deprecated and will become unavailable February 30th, 2025",
  isCloseable: true,
},

Old versions link

The oldVersionsHref property can be used to add an external link to the bottom of the versions dropdown. This is great for scenarios where old versions of a product's documentation are built using something other than Makersaurus, such as MKDocs. The link will be labeled "Previous documentation versions".

On a site with many documentation versions, the version dropdown can grow into a long, flat list. Set groupVersionDropdownByMinor: true in makersaurus.config.js to add a divider line wherever the major.minor changes between two versions, so patches within the same minor stay visually grouped:

groupVersionDropdownByMinor: true,

It's off by default and opt-in. A few things to know:

It applies to the desktop version dropdown only and doesn't change the mobile version picker.
Makersaurus groups versions by the major.minor parsed from each version's label, so v1.7.3 and v1.7.0 share a group while v1.6.60 starts a new one below the divider.
The "current" (Next) version has no version number, so it isn't grouped.
The divider color follows the theme in light and dark mode.

At the bottom of each Markdown page Makersaurus injects a feedback widget. You should be able to find it just below this section. Clicking "submit and view feedback for this page" opens an issue in the docs-issues-requests repository. To change the user automatically assigned to the issue, modify the feedbackAssignee field in makersaurus.config.js.

To automatically apply labels to the issue, use the feedbackLabels property. The value should be an array of strings, eg.

feedbackLabels: ["area/core", "mlops"]

Note that Github will not apply labels to the issue unless the user is a contributor in the docs-issues-requests repository and the labels already exist.

Promoting search results

Use the optional searchFilter property to promote search results for a specific site. You must use one of the tags from docsearch_scraper.json (for example "h2o-ai-cloud" or "h2o-document-ai").

Image zoom

Images in your documentation are click-to-zoom by default. Readers can click any screenshot or diagram in the page body to open it in a lightbox; clicking again (or pressing Escape) closes it. The overlay follows the active color mode. Logos, navbar, and footer images are not affected, and images that link somewhere keep navigating rather than zooming.

Use the optional imageZoom property to turn it off or customize it:

// Turn off zoom entirely
imageZoom: false,

// Or customize it (any field you omit keeps its default)
imageZoom: {
  selector: ".markdown img:not(a img)",
  background: { light: "rgb(255, 255, 255)", dark: "rgb(50, 50, 50)" },
  config: {}, // medium-zoom options: https://github.com/francoischalifour/medium-zoom#options
},

Breadcrumbs

Doc pages show a breadcrumb trail at the top of the page by default. To turn breadcrumbs off across the site, set breadcrumbs to false in makersaurus.config.js:

breadcrumbs: false,

It's a single, site-wide switch and it's on by default, so you only need the option to turn it off. Breadcrumbs appear on doc pages, and the active crumb carries subtle H2O styling.

Steps

Use the <Steps> and <Step> components for numbered procedures. They are available in any MDX file without an import. Each <Step> takes an optional title, and the numbers are added automatically, so you can reorder, add, or remove steps without renumbering.

Install the package
Run npm install @h2oai/makersaurus.
Configure your site
Add a makersaurus.config.js file with your project's title, tagline, and url.
Build the site
Run npm run build to generate the static site.

Write it like this. Each <Step> must be nested in a <Steps>, and you need a blank line above and below the content of each <Step> so its Markdown renders:

<Steps>

<Step title="Install the package">

Run `npm install @h2oai/makersaurus`.

</Step>

<Step title="Build the site">

Run `npm run build` to generate the static site.

</Step>

</Steps>

Nested sub-steps

Nest a <Steps> inside a <Step> to break a step into sub-steps. Makersaurus numbers them hierarchically—2.1, 2.2—and indents them under their parent. Flat procedures keep plain numbers, so nesting stays opt-in per step:

Install the package
Run npm install @h2oai/makersaurus.
Configure your site
Create a makersaurus.config.js:
1. Set the basics
  Add title, tagline, and url.
2. Enable features
  Turn on the markdown features you need, such as math or mermaid.
Build the site
Run npm run build.

Write it by placing a second <Steps> inside a <Step>. The same blank-line rule applies to the nested steps:

<Steps>

<Step title="Configure your site">

Create a `makersaurus.config.js`:

<Steps>

<Step title="Set the basics">

Add `title`, `tagline`, and `url`.

</Step>

</Steps>

</Step>

</Steps>

Figure

Use the <Figure> component for an image with a caption. Markdown has no caption syntax, so <Figure> renders a semantic <figure> / <figcaption>, styled consistently across docs sites. The component works in any MDX file without an import, and—like every content image—a <Figure> image is click-to-zoom.

Pass src and an optional caption, alt, width, and align (center, the default, left, or right):

<Figure
  src="/img/screenshot.png"
  caption="The settings page in dark mode"
  width="480px"
  align="center"
/>

Makersaurus resolves src against your site's baseUrl, so a root-relative path such as /img/screenshot.png works on any deployment. The visible caption already describes the figure. Add alt when the image needs a separate description for screen readers.

Video

Use the <Video> component to embed a responsive video—a local file, or a YouTube or Vimeo URL. It renders the player in a 16:9 frame that scales to the column width and follows the active color mode, and it works in any MDX file without an import.

Pass src plus any optional props: title (an accessible label for the player), controls (shown by default), playing to autoplay, and aspectRatio to override the 16:9 default.

<Video src="https://www.youtube.com/watch?v=lv-_blntJd4" />

To embed a local file, import it and pass the import as src:

import demo from "./demo.mp4";

<Video src={demo} />

Cards

Use <CardGrid> with <Card> children to build a responsive grid of linkable cards, handy for landing pages and section indexes. Both components work in any MDX file without an import. The grid is responsive: one column on narrow screens, two at medium widths, and three when there's room.

Installation

Scaffold a new site and run it locally.

Configuration

Every makersaurus.config.js field, explained.

Reference files

The files Makersaurus reads and generates.

Each <Card> takes a title, an optional icon, an optional href (which turns the whole card into the link), and a description as its children. Set columns on the grid to change the desktop column count:

<CardGrid columns={2}>

<Card title="Get started" icon="🚀" href="/guides/installation">
Install Makersaurus and scaffold your first site.
</Card>

<Card title="API reference" icon="📖" href="/api/config">
Configure your site with makersaurus.config.js.
</Card>

</CardGrid>

The icon renders as-is, so an emoji works with no setup. To use an icon component, import it and pass it in: icon={<MyIcon />}.

Code tabs

Use tabs to show the same content as alternatives—for example, a code sample in Python and R. Give every tab block the same groupId and the reader's choice syncs across the whole page and sticks across pages (it's saved in their browser). Use the shared groupId="language" for language tabs, so a reader picks their language once for the entire site.

Import the components once at the top of the page:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Then write language tab blocks with the same groupId. Pick a language in the first block and the second one follows:

Python
R

import h2o
h2o.init()

library(h2o)
h2o.init()

Python
R

frame = h2o.import_file("data.csv")

frame <- h2o.importFile("data.csv")

Write each block like this:

<Tabs groupId="language">
<TabItem value="py" label="Python">

```py
import h2o
h2o.init()
```

</TabItem>
<TabItem value="r" label="R">

```r
library(h2o)
h2o.init()
```

</TabItem>
</Tabs>

A few conventions keep the sync working:

Use the same groupId ("language") on every language tab block, on every page.
Use consistent values across blocks ("py", "r", and so on), so the choice lands on the matching tab.
The selection persists in the reader's browser, so it carries across pages of the same site (but not to a separate docs site on another domain). To also put it in the URL for shareable links, add queryString: <Tabs groupId="language" queryString>.

Add a related list to a page's frontmatter to show Related content cards at the bottom of that page. Each entry takes a title and an href, plus an optional description. The section appears only on pages that set related, so it's opt-in per page.

---
title: My page
related:
  - title: Installation
    href: /guides/installation
  - title: Configuration
    href: /api/config
    description: Every makersaurus.config.js field.
---

The cards reuse the <Card> component, so they're responsive and dark-mode aware, and the whole card is one click target. This page sets related, so you'll see the cards just below.

Versioned docs don't resolve hrefs per version, so use version-correct paths (for example, /1.2.0/guides/installation) to point at the right version.

Feedback

Submit and view feedback for this page
Send feedback about Makersaurus Docs to cloud-feedback@h2o.ai

Installation

Configuration

Every makersaurus.config.js field.

.css-1jgtvd5{-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;text-align:center;-ms-flex-negative:0;-webkit-flex-shrink:0;flex-shrink:0;width:1em;height:1em;font-size:1.5rem;display:inline-block;overflow:hidden}rocket_launch Dependencies​

Code highlighting​

Injecting text files​

Includes Plugin​

Mermaid​

Math​

Redocusaurus​

Version custom field​

Announcement bar​

Old versions link​

Version dropdown grouping​

Feedback widget​

Promoting search results​

Image zoom​

Breadcrumbs​

Steps​

Nested sub-steps​

Figure​

Video​

Cards​

Code tabs​

Related content​

Related content