Working with Docusaurus

If you're interested in a deep dive on Docusaurus and how it works, check out their docs. This page is intended to serve as a crash course on common conventions within Docusaurus and how they apply to Hasura's docs 🤙

Guides

Also checkout their Guides, they are pretty detailed.

Please check the Advanced Guides to learn in depth about Architecture, Plugins, Routing etc.

docusaurus.config.js

All the magic happens here. SEO, Theme, Plugins, Navbar, Footer, Search Config, and what not...

Please check the API for all possible config options here.

Cleint API - components, hooks etc.

Please check the client API docs for available React components, hooks & modules.

Sidebar

Label & position

For Individual Files

Use of sidebar_label and sidebar_position frontmatter

graphql/core/actions/create.mdx

---
sidebar_label: Creating actions
sidebar_position: 1
---

For Directories (Categories)

By default, index.mdx doc's - sidebar_label & sidebar_position will be applied for directories.

To override, please add a _category_.json and add the label and position properties.

graphql/core/actions/_category_.json

{
  "label": "Actions",
  "position": 3
}

More about Sidebar

You can also create a custom sidebar and add everthing manually.

Checkout Docusaurus Docs for Sidebar - https://docusaurus.io/docs/sidebar

index.mdx file only directories

This is known and default behavior from docusaurus. index is considered direct link to directory index and won't be visible unless there is one more file.

If you only have an index.mdx file, prefer directory.mdx over directory/index.mdx.

URL slug

This only applies for index.mdx files.

index file routes are resolved to directory/ and not directory/index

Use slug metadata to manually set the slug to index. Please check this PR on docusaurus for more information.

graphql/core/actions/index.mdx

---
slug: index
---

Styling

The majority of styles is controlled through CSS variables - there is a heavy list available (use the browser inspect element to see the complete list).

These variables can be overridden and new custom styles to be added in src/css/custom.scss and src/css/_custom-dark.scss for light and dark themes respectively.

React components

Add any new React Components to the src/components/ComponentName directory. Add the index.tsx file and use styles.module.scss for styling to not let this collide with global styles.

Then this component can be imported with @site global directive.

import ComponentName from '@site/src/components/ComponentName';

tip

Check existing components for a better idea.

Static assets

All the static assets lives in static directory.

Asset	Directory
Images	static/img
Fonts	static/fonts
Icons	static/icons

Updating to latest Docusaurus version

Checkout the change log for latest releases and changes involved - https://docusaurus.io/changelog/

Please ensure to check breaking changes and re-swizzle any swizzled components given they are part of breaking changes.

Any swizzled component will be cloned to src/theme.

An Example: The TOCInline and TOCItems components are swizzled and custom logic is added.

The custom added logic (src/theme/TOCInline, src/theme/TOCItems) is indicated by comments - // Customization START and // Customization END. If reswizzled in the future, only these blocks need an update.

toc is a flat array and has no concept of nested tree children structure. This behavior is changed in 2.0.0-beta.16. Please check the Breaking changes that forced us to swizzle.

Docusaurus Support

Join their Discord and ask in #help-and-questions