Skip to main content
Version: current

Getting started

The goal of Makersaurus is to simplify the process of creating documentation for the H2O AI Cloud. Makersaurus also attempts to make it easier to keep our docs internally consistent and up-to-date. From a technical perspective, Makersaurus uses the minimum possible config to scaffold Docusaurus sites on-the-fly with standardized H2O.ai styles, headers, footers, home page, and search.

Prerequisites​

In order to use Makersaurus, you need to install node and npm. Any modern version should be fine, but if you are experiencing difficulties this guide is confirmed to work with node 16.15.1 and npm 8.11.0.

tip

Makersaurus 0.10.0 and below was published to Github's npm registry. Starting with 0.11.0 Makersaurus is published directly to npm. If you see package not found when trying to install newer Makersaurus versions, make sure you remove .npmrc entries that instruct npm to look in the Github npm registry. You can check where your npm is configured to look for packages with the npm config list command.

Running an existing project locally​

Clone the repository that contains the project and navigate to the folder where Makersaurus is set up (look for makersaurus.config.js). In that folder, run the following commands:

npm install @h2oai/makersaurus@latest --global
npm start

The npm start command will download all of the necessary packages, which might take a little while depending on your internet connection and npm's servers. Then it will start Makersaurus on http://localhost:3000/. Navigate to that location in your browser and you should see the project running!

Creating a new project​

To get started, navigate to where you want to create your project and run:

npx @h2oai/makersaurus@latest create-new-project

This command will create a folder called documentation with the following contents:

  • package.json
  • makersaurus.config.js
  • sidebars.js
  • docs
  • .gitignore

We will describe these files in more detail soon, but believe it or not, this is all you need to run a Makersaurus project. Just run:

cd documentation
npm install
npm start

If all goes well, after a short wait your project will be served on port 3000. Take a minute to explore your first Makersaurus site.

Apply templates​

If your Makersaurus project lives within a larger project, there are some built-in tools to help you integrate the docs. First, you can supplement the existing README.md file with information about the docs. Run this command and paste the output into the readme wherever is most appropriate:

npx @h2oai/makersaurus@latest gen-readme

Does the project have a Makefile? If so, you can run this command get a list of docs-related tasks that can be added to the makefile:

npx @h2oai/makersaurus@latest gen-makefile

Now you can run make setup-doc and make run-doc from the project root instead of running npm install and npm start from the Makersaurus directory.

See the templates guide for more information about these commands. There is also a github-pages deployment template.

Next steps​

Turning this example site into a production-ready docs site is as easy as editing the files in the documentation folder.

sidebars.js works exactly the same as it does in a Docusaurus project.

makersaurus.config.js is a slimmer version of docusaurus.config.js - some fields are there but other fields are handled by Makersaurus (such as the logo and navbar configs). See the config docs for more information about how this works.

The docs folder contains all the markdown files you would have in a normal Docusaurus project, in the exact same format. You can include assets here as well. The big difference is index.md, where a special Makersaurus template should be used to keep the home page in sync with other documentation sites. Read more in the home page configuration guide.

Hot reloading​

The development server will pick up any changes you make to the docs folder automatically. For changes to sidebars.js or makersaurus.config.js you will have to stop the process and run npm start again.

Upgrading Makersaurus​

When a new version of Makersaurus is available, navigate to the documentation folder and run:

npm update @h2oai/makersaurus

Go ahead and rerun your project to make sure everything is still looking good, after that this change can be committed and deployed.

Migrating from Docusaurus to Makersaurus​

If you already have an existing Docusaurus site, there is no need to rewrite documentation or redo the sidebar. Follow this process:

  1. Generate a new Makersaurus site using the steps above
  2. Replace the auto-generated docs folder and sidebars.js file with the ones from your old Docusaurus site.
  3. If the docs are versioned, copy versioned_docs, versioned_sidebars, and versions.json from the old site.
  4. Manually update the fields in makersaurus.config.js with correct information, using the old docusaurus.config.js as a guide.
warning

Do not copy and paste everything from docusaurus.config.js into makersaurus.config.js. Many of these properties are not part of the Makersaurus config schema, so you will wind up with an invalid config that causes npm start to fail.

  1. Set up the home page. Note that many old projects use an index.md file, whereas in Makersaurus the home page is set up in makersaurus.config.js. Copy information from index.md into the config file, then delete index.md.
  2. Carefully examine each page of the documentation for issues.
warning

Note that the feedback widget is now added to each page automatically, so if it was added manually in the previous project it will need be removed. Otherwise the feedback widget will appear twice.

Migrating from the old version (0.8.4) of Makersaurus to the new version (0.9.0)​

npm update @h2oai/makersaurus doesn't work for now. We need to migrate the old Makersaurus manually.

Migrate documents​

  1. Generate a new Makersaurus site using the steps above with npx @h2oai/makersaurus@latest create-new-project
  2. Replace the auto-generated docs folder and sidebars.js file with the ones from your old Makersaurus site.
  3. If the docs are versioned, copy versioned_docs, versioned_sidebars, and versions.json from the old site.

@mui icon library change​

replace import Icon from "@material-ui/core/Icon" with import Icon from "@mui/material/Icon"

please refer to this link.

Deployment​

Verify the site is working well locally, then run

npm run deploy
Feedback