Skip to main content
Version: current

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
  • react-player

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.

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​

The Docusaurus Mermaid plugin can be installed by making the following additions to makersaurus.config.js:

{
  ...
  dependencies: {
    ...
    "@docusaurus/theme-mermaid": "2.4.1",
  },
  markdown: {
    mermaid: true,
  }
}

Here is an example diagram:

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,
},

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

Feedback widget​

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

Feedback