Skip to main content
Version: v0.0.4

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. Using a relatively small configuration file, you can scaffold Docusaurus sites on-the-fly with standardized H2O.ai styles, headers, footers, home page, and search.

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.

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.

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​

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

Deployment​

Verify the site is working well locally, then run

npm run deploy
Feedback