3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-24 22:46:57 +02:00
Code Issues Projects Releases Packages Wiki Activity

refactor: normalize Markdown linkification behavior, elaborate in documentation (#7248)

Browse source 
* refactor: normalize Markdown linkification behavior, elaborate in documentation

* fix broken links

* allow links to be relative to site root

* fix test

* minor doc update

* Update website/docs/guides/markdown-features/markdown-features-links.md

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>
This commit is contained in:
Joshua Chen 2022-04-29 11:36:39 +08:00 • committed by GitHub
parent a30daa1530
commit d2562a4434
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 132 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

39
website/docs/guides/docs/docs-markdown-features.mdx
View file

@ -1,39 +0,0 @@
---
id: markdown-features
title: Docs Markdown Features
description: Docusaurus Markdown features that are specific to the docs plugin
slug: /docs-markdown-features
---
Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx) and have a few additional docs-specific Markdown features.
## Markdown front matter {#markdown-front-matter}
Markdown docs have their own [Markdown front matter API](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
## Referencing other documents {#referencing-other-documents}
If you want to reference another document file, you could use the relative path of the document you want to link to.
Docusaurus will convert the file path to be the final document url path (and remove the `.md` extension).
For example, if you are in `folder/doc1.md` and you want to reference `folder/doc2.md`, `folder/subfolder/doc3.md` and `otherFolder/doc4.md`:
```md
I am referencing a [document](doc2.md).
Reference to another [document in a subfolder](subfolder/doc3.md).
[Relative document](../otherFolder/doc4.md) referencing works as well.
```
:::tip
Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits:
- links will keep working on the GitHub interface
- you can customize the document slugs without having to update all the links
- a versioned doc will link to another doc of the exact same version
- relative links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash)
:::