From 284649c7c851bb0a228cc22bbb8811eb91e5c80f Mon Sep 17 00:00:00 2001 From: Kayce Basques Date: Wed, 16 Mar 2022 16:54:18 -0700 Subject: [PATCH] docs: clarify the usage of slug (#6926) * Clarify the usage of slug As a new user it was unclear whether setting `slug` would change the URL relative to the root directory or relative to the docs directory. The example I added should make that clear without needing to test out the functionality in a Docusaurus instance (which is what I had to do). * editorial changes Co-authored-by: Joshua Chen --- website/docs/guides/docs/docs-introduction.md | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/website/docs/guides/docs/docs-introduction.md b/website/docs/guides/docs/docs-introduction.md index 426186a72b..02e9d76b45 100644 --- a/website/docs/guides/docs/docs-introduction.md +++ b/website/docs/guides/docs/docs-introduction.md @@ -37,17 +37,31 @@ id: part1 Lorem ipsum ``` -If you want more control over the last part of the document URL, it is possible to add a `slug` (defaults to the `id`). +### Customizing doc URLs {#customizing-doc-urls} + +By default, a document's URL location is its file path relative to the `docs` folder. Use the `slug` front matter to change a document's URL. + +For example, suppose your site structure looks like this: + +```bash +website # Root directory of your site +└── docs + └── guide + └── hello.md +``` + +By default `hello.md` will be available at `/docs/guide/hello`. You can change its URL location to `/docs/bonjour`: ```md --- -id: part1 -slug: part1.html +slug: /bonjour --- Lorem ipsum ``` +`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](#docs-only-mode) for how to remove the `/docs` part from the URL. + :::note It is possible to use: