Skip to main content

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.

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.

AssetDirectory
Imagesstatic/img
Fontsstatic/fonts
Iconsstatic/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