mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
96646005f7
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7715 Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: 61a91af22333ef08db1ec623941ac9dd5dc50179
128 lines
3.7 KiB
Plaintext
128 lines
3.7 KiB
Plaintext
---
|
|
sidebar_position: 4
|
|
---
|
|
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
|
|
# Links
|
|
|
|
## External Links
|
|
|
|
`[Hasura Cloud](https://cloud.hasura.io/signup/)`
|
|
|
|
## Internal links
|
|
|
|
Since MDX doesn't yet support this direct referencing, we have to rely on relative/root relative path resolution for
|
|
[referencing other documents](https://docusaurus.io/docs/docs-markdown-features#referencing-other-documents).
|
|
|
|
```markdown
|
|
[Get started With Hasura Cloud](../relative/path/to/getting-started-document.mdx)
|
|
|
|
[Remote Schemas](../relative/path/to/remote-schemas-document.mdx)
|
|
```
|
|
|
|
### Root Relative Links
|
|
|
|
While relative paths works absolutely fine, this can easily lead to an absolute mess when files are moved around. Thus
|
|
requiring manual effort to fix the paths.
|
|
|
|
To avoid this scenario, we can use root relative paths. The path will still break when moved around, but it is lot
|
|
easier to find and replace. Find with old path and replace with new path.
|
|
|
|
```
|
|
Find `/folder1/subfolder2/doc3.mdx` and replace with `/folder1/newsubfolder4/doc5.mdx`
|
|
```
|
|
|
|
The root relative link should start after the `latest` directory level.
|
|
|
|
```
|
|
[MDX Root Relative Actions Link](/actions/overview.mdx)
|
|
```
|
|
|
|
:::tip Don't forget the extension!
|
|
|
|
Make sure to include file extension as MDX links are parsed as a file path and will be resolved correctly.
|
|
|
|
:::
|
|
|
|
:::danger be cautious with URL slug
|
|
|
|
If we add an `id` Metadata for the document, the url slug for this page will be overridden to `id` as opposed to default
|
|
filename. Thus requiring us to set a slug if we intend to leave it default.
|
|
|
|
So, we can skip the top level id in Metadata as it is by default the filename without extension.
|
|
|
|
Read more about it from [Docusaurus Document Id Section](https://docusaurus.io/docs/docs-introduction#document-id)
|
|
|
|
:::
|
|
|
|
To avoid repetetion of adding dull path for each link, we could take advantage of
|
|
[reference-style-links](https://daringfireball.net/projects/markdown/syntax#link) syntax in markdown.
|
|
|
|
:::tip Managing repeated Links in same doc
|
|
|
|
If a same doc is linked in multiple sections, prever keeping it in a variable and reuse for better maintainability.
|
|
|
|
Add these variables at the end of file for easier reference, and Add a HTML comment `<!-- Shared Link Variables -->` to
|
|
represent its a variable section.
|
|
|
|
Please refer [this](https://daringfireball.net/projects/markdown/syntax#link) for better understaning of
|
|
reference-style-links in markdown.
|
|
|
|
For Example:
|
|
|
|
```markdown
|
|
## Section one
|
|
|
|
.....
|
|
|
|
REST ... [create_action][metadata-create-action] or [update_action][metadata-update-action] Metadata APIs ...
|
|
[request_transform][requesttransformation] field ...:
|
|
|
|
....
|
|
|
|
## Section two
|
|
|
|
.....
|
|
|
|
REST ... [create_action][metadata-create-action] or [update_action][metadata-update-action] Metadata APIs ...
|
|
[request_transform][requesttransformation] field ...:
|
|
|
|
....
|
|
|
|
<!-- Shared Link Variables -->
|
|
|
|
[metadata-create-action]: /api-reference/metadata-api/actions.mdx#metadata-create-action
|
|
[metadata-update-action]: /api-reference/metadata-api/actions.mdx#metadata-update-action
|
|
[requesttransformation]: /api-reference/syntax-defs.mdx#requesttransformation
|
|
```
|
|
|
|
:::
|
|
|
|
## Links in React
|
|
|
|
Use Docusaurus [Links](https://docusaurus.io/docs/docusaurus-core#link) for linking in React. Works for both internal
|
|
and external links.
|
|
|
|
```jsx
|
|
import Link from '@docusaurus/Link';
|
|
|
|
// Internal Link
|
|
<Link to="/rst-vs-mdx-guide/links#root-relative-links">Root Relative Links</Link>
|
|
|
|
// External Link
|
|
<Link to="https://hasura.io">Hasura</Link>
|
|
```
|
|
|
|
<hr />
|
|
|
|
:::info
|
|
|
|
React Link's `to` attribute will always accept a URL path and not file path.
|
|
|
|
Docusaurus catches [broken markdown links](https://docusaurus.io/docs/api/docusaurus-config#onbrokenmarkdownlinks) if
|
|
enabled
|
|
|
|
:::
|