From 324c853da08c6dd4a78fe34ec014e6dabe20e820 Mon Sep 17 00:00:00 2001 From: Joshua Chen Date: Mon, 4 Mar 2024 06:33:17 -0500 Subject: [PATCH] docs: emphasize "index slug" convention (#9906) --- website/docs/guides/docs/docs-create-doc.mdx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/website/docs/guides/docs/docs-create-doc.mdx b/website/docs/guides/docs/docs-create-doc.mdx index 6f1e02992ef3..86fc7c2a8e4a 100644 --- a/website/docs/guides/docs/docs-create-doc.mdx +++ b/website/docs/guides/docs/docs-create-doc.mdx @@ -112,7 +112,21 @@ The ID is used to refer to a document when hand-writing sidebars, or when using ### Doc URLs {#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. +By default, a document's URL location is its file path relative to the `docs` folder, with a few exceptions. Namely, if a file is named one the following, the file name won't be included in the URL: + +- Named as `index` (case-insensitive): `docs/Guides/index.md` +- Named as `README` (case-insensitive): `docs/Guides/README.mdx` +- Same name as parent folder: `docs/Guides/Guides.md` + +In all cases, the default slug would only be `/Guides`, without the `/index`, `/README`, or duplicate `/Guides` segment. + +:::note + +This convention is exactly the same as [the category index convention](./sidebar/autogenerated.mdx#category-index-convention). However, the `isCategoryIndex` configuration does _not_ affect the document URL. + +::: + +Use the `slug` front matter to change a document's URL. For example, suppose your site structure looks like this: