mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
03cf883a46
[DOCS-256]: https://hasurahq.atlassian.net/browse/DOCS-256?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7520 GitOrigin-RevId: 41ae163de3747164ef4b01cfcd155ecb941510bb
121 lines
3.1 KiB
Plaintext
121 lines
3.1 KiB
Plaintext
---
|
|
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
|
|
|
|
<!-- 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.
|
|
|
|
```markdown
|
|
[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)
|
|
```
|
|
|
|
:::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.
|