diff --git a/docs/basic-usage.md b/docs/basic-usage.md
index 6dcc966ef68..e484d8ca989 100644
--- a/docs/basic-usage.md
+++ b/docs/basic-usage.md
@@ -58,7 +58,7 @@ build-backend = "poetry.core.masonry.api"
 Poetry assumes your package contains a package with the same name as `tool.poetry.name`.
 If this is not the case, populate `tool.poetry.packages` to specify your package or packages.
 
-See [Packages](/docs/pyproject#packages) for more information.
+See [Packages]({{< relref "pyproject#packages" >}}) for more information.
 
 ### Initialising a pre-existing project
 
diff --git a/docs/cli.md b/docs/cli.md
index 0e845385a9f..6935c6fbd35 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -565,7 +565,7 @@ The `check` command validates the structure of the `pyproject.toml` file
 and returns a detailed report if there are any errors.
 
 {{% note %}}
-This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-check) for more information.
+This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-check">}}) for more information.
 {{% /note %}}
 
 ```bash
@@ -586,7 +586,7 @@ This command locks (without installing) the dependencies specified in `pyproject
 
 {{% note %}}
 By default, this will lock all dependencies to the latest available compatible versions. To only refresh the lock file, use the `--no-update` option.
-This command is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-lock) for more information.
+This command is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-lock">}}) for more information.
 {{% /note %}}
 
 ```bash
@@ -644,7 +644,7 @@ poetry export -f requirements.txt --output requirements.txt
 
 {{% note %}}
 This command is provided by the [Export Poetry Plugin](https://github.com/python-poetry/poetry-plugin-export)
-and is also available as a pre-commit hook. See [pre-commit hooks](/docs/pre-commit-hooks#poetry-export) for more information.
+and is also available as a pre-commit hook. See [pre-commit hooks]({{< relref "pre-commit-hooks#poetry-export" >}}) for more information.
 {{% /note %}}
 
 {{% note %}}
diff --git a/docs/dependency-specification.md b/docs/dependency-specification.md
index 9291fc754e2..0bb79368724 100644
--- a/docs/dependency-specification.md
+++ b/docs/dependency-specification.md
@@ -190,9 +190,14 @@ for a dependency as shown here.
 gunicorn = { version = "^20.1", extras = ["gevent"] }
 ```
 
+{{% note %}}
+These activate extra defined for the dependency, to configure an optional dependency
+for extras in your project refer to [`extras`]({{< relref "pyproject#extras" >}}).
+{{% /note %}}
+
 ## `source` dependencies
 
-To depend on a package from an [alternate repository](/docs/repositories/#install-dependencies-from-a-private-repository),
+To depend on a package from an [alternate repository]({{< relref "repositories/#install-dependencies-from-a-private-repository" >}}),
 you can use the `source` property:
 
 ```toml
diff --git a/docs/faq.md b/docs/faq.md
index 445b0e6e505..61be7c91224 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -104,7 +104,7 @@ The current project's Python requirement (>=3.7.0,<4.0.0) is not compatible with
 ```
 
 Usually you will want to match the Python requirement of your project with the upper bound of the failing dependency.
-Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions](/docs/dependency-specification/#multiple-constraints-dependencies),
+Alternative you can tell Poetry to install this dependency [only for a specific range of Python versions]({{< relref "dependency-specification#multiple-constraints-dependencies" >}}),
 if you know that it's not needed in all versions.
 
 
diff --git a/docs/pre-commit-hooks.md b/docs/pre-commit-hooks.md
index c5de4f0c4fb..a032c10e6cd 100644
--- a/docs/pre-commit-hooks.md
+++ b/docs/pre-commit-hooks.md
@@ -33,7 +33,7 @@ to make sure the poetry configuration does not get committed in a broken state.
 ### Arguments
 
 The hook takes the same arguments as the poetry command.
-For more information see the [check command](/docs/cli#check).
+For more information see the [check command]({{< relref "cli#check" >}}).
 
 
 ## poetry-lock
@@ -44,7 +44,7 @@ to make sure the lock file is up-to-date when committing changes.
 ### Arguments
 
 The hook takes the same arguments as the poetry command.
-For more information see the [lock command](/docs/cli#lock).
+For more information see the [lock command]({{< relref "cli#lock" >}}).
 
 
 ## poetry-export
@@ -59,7 +59,7 @@ It is recommended to run the [`poetry-lock`](#poetry-lock) hook prior to this on
 ### Arguments
 
 The hook takes the same arguments as the poetry command.
-For more information see the [export command](/docs/cli#export).
+For more information see the [export command]({{< relref "cli#export" >}}).
 
 The default arguments are `args: ["-f", "requirements.txt", "-o", "requirements.txt"]`,
 which will create/update the requirements.txt file in the current working directory.
diff --git a/docs/pyproject.md b/docs/pyproject.md
index b8ccf91dbd4..5f041e7d3e0 100644
--- a/docs/pyproject.md
+++ b/docs/pyproject.md
@@ -236,7 +236,7 @@ The globs specified in the exclude field identify a set of files that are not in
 If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (`.gitignore` for git for example).
 
 {{% note %}}
-Implicitly declaring entries in `include` will negate VCS' ignore settings.
+Explicitly declaring entries in `include` will negate VCS' ignore settings.
 {{% /note %}}
 
 ```toml