Skip to main content

Links

[Hasura Cloud](https://cloud.hasura.io/signup/)

Since MDX doesn't yet support this direct referencing, we have to rely on relative/root relative path resolution for referencing other documents.

[Getting Started With Hasura Cloud](../relative/path/to/getting-started-document.mdx)

[Remote Schemas](../relative/path/to/remote-schemas-document.mdx)

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/index.mdx)
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.

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

To avoid repetetion of adding dull path for each link, we could take advantage of reference-style-links syntax in markdown.

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 for better understaning of reference-style-links in markdown.

For Example:

## 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

Use Docusaurus Links for linking in React. Works for both internal and external links.

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>
info

React Link's to attribute will always accept a URL path and not file path.

Docusaurus catches broken markdown links if enabled