--- description: Working with Heading and Heading Ids - also custom Heading Ids sidebar_position: 2 --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Headings & Ids ## Headings Please follow good old `h1(#) => h6(######)` hierarchy. ```markdown # 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 :::info 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 {#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: ```markdown ## Heading H2 example heading-h2-example ``` To link to this section, we can append the id as a `#hash-param` to url. ```markdown [Link to Sub Section](/path/to/sub/section.mdx#heading-h2-example)`. [Link to sub section in same document](#heading-ids) ``` :::caution 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. ```markdown {1} ## 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](https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir) - 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. :::danger Please do not add id in frontmatter Docusaurus by default uses [file path (including folders) without the extension as the id](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#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](https://docusaurus.io/docs/markdown-features/headings) for more insights into usage and customization.