From b864bc2b26e191da5e631bdc0625ca63ce6224ea Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 27 Apr 2022 11:08:49 +0800 Subject: [PATCH 1/6] refactor: normalize Markdown linkification behavior, elaborate in documentation --- .../__tests__/__fixtures__/docs/doc2.md | 2 +- .../src/markdown/__tests__/linkify.test.ts | 2 +- .../__snapshots__/markdownLinks.test.ts.snap | 32 +++++++++++++ .../src/__tests__/markdownLinks.test.ts | 29 ++++++++++++ .../docusaurus-utils/src/markdownLinks.ts | 14 ++++-- .../guides/docs/docs-markdown-features.mdx | 39 --------------- .../markdown-features-links.md | 47 +++++++++++++++++++ website/sidebars.js | 2 +- 8 files changed, 121 insertions(+), 46 deletions(-) delete mode 100644 website/docs/guides/docs/docs-markdown-features.mdx create mode 100644 website/docs/guides/markdown-features/markdown-features-links.md diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md index e41f1fe6bdb2..542405177b8c 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc2.md @@ -9,4 +9,4 @@ - [doc1](doc1.md) - [doc2](./doc2.md) -- [doc-localized](./doc-localized.md) +- [doc-localized](/doc-localized.md) diff --git a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts index 451bec66ccac..0ca367836157 100644 --- a/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts @@ -75,7 +75,7 @@ const sourceToPermalink: SourceToPermalink = { '@site/i18n/fr/docusaurus-plugin-content-docs/current/doc-localized.md': '/fr/doc-localized', - '@site/docs/doc-localized': '/doc-localized', + '@site/docs/doc-localized.md': '/doc-localized', }; function createMarkdownOptions( diff --git a/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap b/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap index f8d2b1f78741..e7ba1ad8d060 100644 --- a/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap +++ b/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap @@ -134,3 +134,35 @@ The following operations are defined for [URI]s: ", } `; + +exports[`replaceMarkdownLinks resolves absolute and relative links differently 1`] = ` +{ + "brokenMarkdownLinks": [ + { + "contentPaths": { + "contentPath": "docs", + "contentPathLocalized": "i18n/docs-localized", + }, + "filePath": "docs/intro/intro.md", + "link": "./api/classes/divine_uri.URI.md", + }, + { + "contentPaths": { + "contentPath": "docs", + "contentPathLocalized": "i18n/docs-localized", + }, + "filePath": "docs/intro/intro.md", + "link": "/another.md", + }, + ], + "newContent": " +[Relative link](/docs/another) +[Relative link 2](/docs/api/classes/uri) +[Relative link that should be absolute](./api/classes/divine_uri.URI.md) +[Absolute link](/docs/api/classes/uri) +[Absolute link that should be relative](/another.md) +[Relative link that acts as absolute](/docs/api/classes/uri) +[Relative link that acts as relative](/docs/another) +", +} +`; diff --git a/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts b/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts index 586a0ab7302d..618d185c77f5 100644 --- a/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts +++ b/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts @@ -67,6 +67,35 @@ The following operations are defined for [URI]s: ).toMatchSnapshot(); }); + it('resolves absolute and relative links differently', () => { + expect( + replaceMarkdownLinks({ + siteDir: '.', + filePath: 'docs/intro/intro.md', + contentPaths: { + contentPath: 'docs', + contentPathLocalized: 'i18n/docs-localized', + }, + + sourceToPermalink: { + '@site/docs/intro/intro.md': '/docs/intro', + '@site/docs/intro/another.md': '/docs/another', + '@site/docs/api/classes/divine_uri.URI.md': '/docs/api/classes/uri', + }, + + fileString: ` +[Relative link](./another.md) +[Relative link 2](../api/classes/divine_uri.URI.md) +[Relative link that should be absolute](./api/classes/divine_uri.URI.md) +[Absolute link](/api/classes/divine_uri.URI.md) +[Absolute link that should be relative](/another.md) +[Relative link that acts as absolute](api/classes/divine_uri.URI.md) +[Relative link that acts as relative](another.md) +`, + }), + ).toMatchSnapshot(); + }); + // TODO bad it('ignores links in HTML comments', () => { expect( diff --git a/packages/docusaurus-utils/src/markdownLinks.ts b/packages/docusaurus-utils/src/markdownLinks.ts index fe8353646cd1..7e8881261496 100644 --- a/packages/docusaurus-utils/src/markdownLinks.ts +++ b/packages/docusaurus-utils/src/markdownLinks.ts @@ -111,12 +111,18 @@ export function replaceMarkdownLinks({ // Replace it to correct html link. const mdLink = mdMatch.groups!.filename!; - const sourcesToTry = [ - path.dirname(filePath), - ...getContentPathList(contentPaths), - ].map((p) => path.join(p, decodeURIComponent(mdLink))); + const sourcesToTry: string[] = []; + // ./file.md and ../file.md are always relative to the current file + if (!mdLink.startsWith('./') && !mdLink.startsWith('../')) { + sourcesToTry.push(...getContentPathList(contentPaths)); + } + // /file.md is always relative to the content path + if (!mdLink.startsWith('/')) { + sourcesToTry.push(path.dirname(filePath)); + } const aliasedSourceMatch = sourcesToTry + .map((p) => path.join(p, decodeURIComponent(mdLink))) .map((source) => aliasedSitePath(source, siteDir)) .find((source) => sourceToPermalink[source]); diff --git a/website/docs/guides/docs/docs-markdown-features.mdx b/website/docs/guides/docs/docs-markdown-features.mdx deleted file mode 100644 index 40be16cb9e54..000000000000 --- a/website/docs/guides/docs/docs-markdown-features.mdx +++ /dev/null @@ -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) - -::: diff --git a/website/docs/guides/markdown-features/markdown-features-links.md b/website/docs/guides/markdown-features/markdown-features-links.md new file mode 100644 index 000000000000..ae797d5b284a --- /dev/null +++ b/website/docs/guides/markdown-features/markdown-features-links.md @@ -0,0 +1,47 @@ +--- +id: links +description: Links to other pages in Markdown +slug: /markdown-features/links +--- + +# Markdown links + +There are two ways of adding a link to another page: through a **URL path** and a **file path**. + +```md +[URL path to another document](./installation) [file path to another document](./installation.md) +``` + +URL paths are unprocessed by Docusaurus, and you can see them as directly rendering to ``, i.e. it will be resolved according to the page's URL location, rather than its file-system location. + +If you want to reference another Markdown file **included by the same plugin**, you could use the relative path of the document you want to link to. Docusaurus' Markdown loader will convert the file path to the target file's URL path (and hence remove the `.md` extension). + +For example, if you are in `docs/folder/doc1.md` and you want to reference `docs/folder/doc2.md`, `docs/folder/subfolder/doc3.md` and `docs/otherFolder/doc4.md`: + +```md title="docs/folder/doc1.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. +``` + +Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. Note that absolute paths are **not** resolved relative to the site directory, because that means you have to change all `/docs/` paths to their localized counterparts during localization. + +```md +You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`). +``` + +Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits: + +- Links will keep working on the GitHub interface and many Markdown editors +- You can customize the files' slugs without having to update all the links +- Moving files around the folders can be tracked by your editor, and some editors may automatically update file links +- A [versioned doc](../docs/versioning.md) will link to another doc of the exact same version +- Relative URL links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash) + +:::warning + +Markdown file references only work when the source and target files are processed by the same plugin instance. This is a technical limitation of our Markdown processing architecture and will be fixed in the future. If you are linking files between plugins (e.g. linking to a doc page from a blog post), you have to use URL links. + +::: diff --git a/website/sidebars.js b/website/sidebars.js index ab1729b93e09..99f079461515 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -61,7 +61,6 @@ const sidebars = { ], }, 'guides/docs/versioning', - 'guides/docs/markdown-features', 'guides/docs/multi-instance', ], }, @@ -81,6 +80,7 @@ const sidebars = { 'guides/markdown-features/headings', 'guides/markdown-features/inline-toc', 'guides/markdown-features/assets', + 'guides/markdown-features/links', 'guides/markdown-features/plugins', 'guides/markdown-features/math-equations', 'guides/markdown-features/head-metadata', From 45ed34fba7ca13f81f5dd25956f75ae65edef16d Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 27 Apr 2022 11:38:10 +0800 Subject: [PATCH 2/6] fix broken links --- website/docs/advanced/plugins.md | 2 +- website/docs/installation.md | 2 +- .../versioned_docs/version-2.0.0-beta.17/advanced/plugins.md | 2 +- .../versioned_docs/version-2.0.0-beta.18/advanced/plugins.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/advanced/plugins.md b/website/docs/advanced/plugins.md index 152f8ffebd11..29910ff0e2f9 100644 --- a/website/docs/advanced/plugins.md +++ b/website/docs/advanced/plugins.md @@ -4,7 +4,7 @@ Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin ## Creating plugins {#creating-plugins} -A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). +A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.md). ### Function definition {#function-definition} diff --git a/website/docs/installation.md b/website/docs/installation.md index 944f9f8c2d77..8bf565990ccd 100644 --- a/website/docs/installation.md +++ b/website/docs/installation.md @@ -134,7 +134,7 @@ my-website ### Project structure rundown {#project-structure-rundown} - `/blog/` - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the `path` option. More details can be found in the [blog guide](blog.mdx) -- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the `path` option. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx) +- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the `path` option. More details can be found in the [docs guide](./guides/docs/docs-introduction.md) - `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing - `/src/pages` - Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the [pages guide](guides/creating-pages.md) - `/static/` - Static directory. Any contents inside here will be copied into the root of the final `build` directory diff --git a/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md index 2960263eca6e..5e45b9d82bfa 100644 --- a/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md +++ b/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md @@ -4,7 +4,7 @@ Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin ## Creating plugins {#creating-plugins} -A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). +A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.md). ### Function definition {#function-definition} diff --git a/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md b/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md index 2960263eca6e..5e45b9d82bfa 100644 --- a/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md +++ b/website/versioned_docs/version-2.0.0-beta.18/advanced/plugins.md @@ -4,7 +4,7 @@ Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin ## Creating plugins {#creating-plugins} -A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](./api/plugin-methods/README.md). +A plugin is a function that takes two parameters: `context` and `options`. It returns a plugin instance object (or a promise). You can create plugins as functions or modules. For more information, refer to the [plugin method references section](../api/plugin-methods/README.md). ### Function definition {#function-definition} From ab514384478edd4f97be13863b2049e00105d619 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 27 Apr 2022 23:18:29 +0800 Subject: [PATCH 3/6] allow links to be relative to site root --- packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts | 1 + packages/docusaurus-utils/src/markdownLinks.ts | 2 +- .../docs/guides/markdown-features/markdown-features-links.md | 4 +++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts b/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts index 618d185c77f5..d47b3ab3e2db 100644 --- a/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts +++ b/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts @@ -88,6 +88,7 @@ The following operations are defined for [URI]s: [Relative link 2](../api/classes/divine_uri.URI.md) [Relative link that should be absolute](./api/classes/divine_uri.URI.md) [Absolute link](/api/classes/divine_uri.URI.md) +[Absolute link from site dir](/docs/api/classes/divine_uri.URI.md) [Absolute link that should be relative](/another.md) [Relative link that acts as absolute](api/classes/divine_uri.URI.md) [Relative link that acts as relative](another.md) diff --git a/packages/docusaurus-utils/src/markdownLinks.ts b/packages/docusaurus-utils/src/markdownLinks.ts index 7e8881261496..3a7966ad8db7 100644 --- a/packages/docusaurus-utils/src/markdownLinks.ts +++ b/packages/docusaurus-utils/src/markdownLinks.ts @@ -114,7 +114,7 @@ export function replaceMarkdownLinks({ const sourcesToTry: string[] = []; // ./file.md and ../file.md are always relative to the current file if (!mdLink.startsWith('./') && !mdLink.startsWith('../')) { - sourcesToTry.push(...getContentPathList(contentPaths)); + sourcesToTry.push(...getContentPathList(contentPaths), siteDir); } // /file.md is always relative to the content path if (!mdLink.startsWith('/')) { diff --git a/website/docs/guides/markdown-features/markdown-features-links.md b/website/docs/guides/markdown-features/markdown-features-links.md index ae797d5b284a..7f7d1e335769 100644 --- a/website/docs/guides/markdown-features/markdown-features-links.md +++ b/website/docs/guides/markdown-features/markdown-features-links.md @@ -26,7 +26,9 @@ Reference to another [document in a subfolder](subfolder/doc3.md). [Relative document](../otherFolder/doc4.md) referencing works as well. ``` -Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. Note that absolute paths are **not** resolved relative to the site directory, because that means you have to change all `/docs/` paths to their localized counterparts during localization. +Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. + +Absolute file paths can also be relative to the site directory. However, beware that links that begin with `docs/` or `blog/` are not portable as you would need to manually update them if you create new doc versions or localize them. ```md You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`). From f11de84bd9c2a9d51e786e2f76dff82983203b4f Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 27 Apr 2022 23:35:45 +0800 Subject: [PATCH 4/6] fix test --- .../src/__tests__/__snapshots__/markdownLinks.test.ts.snap | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap b/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap index e7ba1ad8d060..56c08fd6f9e1 100644 --- a/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap +++ b/packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap @@ -160,6 +160,7 @@ exports[`replaceMarkdownLinks resolves absolute and relative links differently 1 [Relative link 2](/docs/api/classes/uri) [Relative link that should be absolute](./api/classes/divine_uri.URI.md) [Absolute link](/docs/api/classes/uri) +[Absolute link from site dir](/docs/api/classes/uri) [Absolute link that should be relative](/another.md) [Relative link that acts as absolute](/docs/api/classes/uri) [Relative link that acts as relative](/docs/another) From bb37bff1cedbac6085f3c8d2a10192e1cde0a3a5 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Wed, 27 Apr 2022 23:39:34 +0800 Subject: [PATCH 5/6] minor doc update --- .../guides/markdown-features/markdown-features-links.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/markdown-features/markdown-features-links.md b/website/docs/guides/markdown-features/markdown-features-links.md index 7f7d1e335769..0adcac11fddd 100644 --- a/website/docs/guides/markdown-features/markdown-features-links.md +++ b/website/docs/guides/markdown-features/markdown-features-links.md @@ -9,7 +9,8 @@ slug: /markdown-features/links There are two ways of adding a link to another page: through a **URL path** and a **file path**. ```md -[URL path to another document](./installation) [file path to another document](./installation.md) +- [URL path to another document](./installation) +- [file path to another document](./installation.md) ``` URL paths are unprocessed by Docusaurus, and you can see them as directly rendering to ``, i.e. it will be resolved according to the page's URL location, rather than its file-system location. @@ -28,10 +29,12 @@ Reference to another [document in a subfolder](subfolder/doc3.md). Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. -Absolute file paths can also be relative to the site directory. However, beware that links that begin with `docs/` or `blog/` are not portable as you would need to manually update them if you create new doc versions or localize them. +Absolute file paths can also be relative to the site directory. However, beware that links that begin with `docs/` or `blog/` are **not portable** as you would need to manually update them if you create new doc versions or localize them. ```md You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`). + +You can also write [links](/docs/otherFolder/doc4.md) relative to the site directory, but it's not recommended. ``` Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits: From 3a131b4ac29b8dde8f9594b2efc12428ddef03c1 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Fri, 29 Apr 2022 10:36:51 +0800 Subject: [PATCH 6/6] Update website/docs/guides/markdown-features/markdown-features-links.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sébastien Lorber --- .../docs/guides/markdown-features/markdown-features-links.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/markdown-features/markdown-features-links.md b/website/docs/guides/markdown-features/markdown-features-links.md index 0adcac11fddd..8fdb6f1fe88f 100644 --- a/website/docs/guides/markdown-features/markdown-features-links.md +++ b/website/docs/guides/markdown-features/markdown-features-links.md @@ -29,7 +29,7 @@ Reference to another [document in a subfolder](subfolder/doc3.md). Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. -Absolute file paths can also be relative to the site directory. However, beware that links that begin with `docs/` or `blog/` are **not portable** as you would need to manually update them if you create new doc versions or localize them. +Absolute file paths can also be relative to the site directory. However, beware that links that begin with `/docs/` or `/blog/` are **not portable** as you would need to manually update them if you create new doc versions or localize them. ```md You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`).