Skip to main content

Headings & Ids

Headings​

Please follow good old h1(#) => h6(######) hierarchy.

# This is the Main Page Title

## This is a H2 heading

### This is a H3 heading

#### This is a H4 heading

##### This is a H5 heading

###### This is a H6 heading

Which renders out as:

This is the Main Page Title

This is a H2 heading​

This is a H3 heading​

This is a H4 heading​

This is a H5 heading​
This is a H6 heading​
Note

At any point of time there should only be one h1 per doc. h2 => h6 can be any number as required while ensuring correct hierarchy.

Heading Ids​

Docusaurus will by default generate an id for each heading to be able to link to individual sections.

The generated id's are nothing but the kebab-cased-heading-text-itself.

Ex:

## Heading H2 example

<!-- will have a generated id as below -->

heading-h2-example

To link to this section, we can append the id as a #hash-param to url.

[Link to Sub Section](/path/to/sub/section.mdx#heading-h2-example)`.

<!-- or just the hash-param if its in the same document -->

[Link to sub section in same document](#heading-ids)
Handling changes to heading

This works as long as there is no change in the respective section heading. Updating the heading would require scanning all the links to this section and updating it every time.

So, to avoid this manual effort and making the links independent, prefer adding a custom id while linking respective section.

Handling custom ids​

Custom Heading Ids are added as {#kebab-cased-id}

Prefer lowercased-kebab-case for all the ids to maintain consistency.

## Step 1: Create a Hasura Cloud project {#create-hasura-project-aws-rds-aurora}

On the Hasura Cloud dashboard, create a new project:

They can also be generated when required using the cli command write-heading-ids - Please DO NOT OVERRIDE existing ones.

Skip for h1 (#) as the top level heading is beginining of file the direct link without #hash-param would work fine.

Please do not add id in frontmatter

Docusaurus by default uses file path (including folders) without the extension as the id and the same will be slug.

If an id is added in frontmatter the slug will by default be the id thus breaking the existing URL structure.

This will result in setting up bunch of redirects and will have a impact on SEO and indexed page rankings.

So, Please ignore the id in frontmatter, Let's leave this to docusaurus default behavior which is great.

In case, if you are not sure of what to do in a different situation. Please let us know, we will help figure out

Please refer to the Docusaurus docs on Headings for more insights into usage and customization.

Last updated on