diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md index 1b89836868..24d8b672e1 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/simple-site/docs/hello.md @@ -1,6 +1,7 @@ --- id: hello title: Hello, World ! +sidebar_label: Hello sidebar_label --- Hi, Endilie here :) diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap index 722dd3df64..adfcdc6be9 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__snapshots__/index.test.ts.snap @@ -208,7 +208,7 @@ Object { \\"permalink\\": \\"/docs/foo/bar\\" }, \\"next\\": { - \\"title\\": \\"Hello, World !\\", + \\"title\\": \\"Hello sidebar_label\\", \\"permalink\\": \\"/docs/\\" } }", @@ -238,7 +238,8 @@ Object { \\"version\\": \\"current\\", \\"frontMatter\\": { \\"id\\": \\"hello\\", - \\"title\\": \\"Hello, World !\\" + \\"title\\": \\"Hello, World !\\", + \\"sidebar_label\\": \\"Hello sidebar_label\\" }, \\"sidebar\\": \\"docs\\", \\"previous\\": { @@ -435,7 +436,7 @@ Object { }, { \\"type\\": \\"link\\", - \\"label\\": \\"Hello, World !\\", + \\"label\\": \\"Hello sidebar_label\\", \\"href\\": \\"/docs/\\" } ] @@ -447,7 +448,7 @@ Object { \\"items\\": [ { \\"type\\": \\"link\\", - \\"label\\": \\"Hello, World !\\", + \\"label\\": \\"Hello sidebar_label\\", \\"href\\": \\"/docs/\\" } ] diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts index d23cc73852..1d27acf4f8 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/docs.test.ts @@ -201,6 +201,7 @@ describe('simple site', () => { frontMatter: { id: 'hello', title: 'Hello, World !', + sidebar_label: 'Hello sidebar_label', }, }); }); @@ -230,6 +231,7 @@ describe('simple site', () => { frontMatter: { id: 'hello', title: 'Hello, World !', + sidebar_label: 'Hello sidebar_label', }, }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts index 77c8d3db4d..8efde44476 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts @@ -328,6 +328,39 @@ describe('simple website', () => { expect(content.loadedVersions.length).toEqual(1); const [currentVersion] = content.loadedVersions; + expect(findDocById(currentVersion, 'foo/baz')).toEqual({ + ...defaultDocMetadata, + version: 'current', + id: 'foo/baz', + unversionedId: 'foo/baz', + sourceDirName: 'foo', + isDocsHomePage: false, + permalink: '/docs/foo/bazSlug.html', + slug: '/foo/bazSlug.html', + previous: { + title: 'Bar', + permalink: '/docs/foo/bar', + }, + next: { + title: 'Hello sidebar_label', + permalink: '/docs/', + }, + sidebar: 'docs', + source: path.posix.join( + '@site', + posixPath(path.relative(siteDir, currentVersion.contentPath)), + 'foo', + 'baz.md', + ), + title: 'baz', + description: 'Images', + frontMatter: { + id: 'baz', + title: 'baz', + slug: 'bazSlug.html', + }, + }); + expect(findDocById(currentVersion, 'hello')).toEqual({ ...defaultDocMetadata, version: 'current', @@ -352,6 +385,7 @@ describe('simple website', () => { frontMatter: { id: 'hello', title: 'Hello, World !', + sidebar_label: 'Hello sidebar_label', }, }); diff --git a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts index 035dd1d468..692bd6ccf2 100644 --- a/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts +++ b/packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts @@ -11,21 +11,7 @@ import { JoiFrontMatter as Joi, // Custom instance for frontmatter validateFrontMatter, } from '@docusaurus/utils-validation'; - -export type DocFrontMatter = { - id?: string; - title?: string; - hide_title?: boolean; - hide_table_of_contents?: boolean; - keywords?: string[]; - image?: string; - description?: string; - slug?: string; - sidebar_label?: string; - sidebar_position?: number; - custom_edit_url?: string | null; - parse_number_prefixes?: boolean; -}; +import {DocFrontMatter} from './types'; // NOTE: we don't add any default value on purpose here // We don't want default values to magically appear in doc metadatas and props diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 76eb8af6d8..8875a1700c 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -198,10 +198,13 @@ export default function pluginContentDocs( previousId, nextId, } = sidebarsUtils.getDocNavigation(doc.id); - const toDocNavLink = (navDocId: string): DocNavLink => ({ - title: docsBaseById[navDocId].title, - permalink: docsBaseById[navDocId].permalink, - }); + const toDocNavLink = (navDocId: string): DocNavLink => { + const {title, permalink, frontMatter} = docsBaseById[navDocId]; + return { + title: frontMatter.sidebar_label ?? title, + permalink, + }; + }; return { ...doc, sidebar: sidebarName, diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 1ae535e2e3..8dad114399 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -181,9 +181,19 @@ export type LastUpdateData = { lastUpdatedBy?: string; }; -export type FrontMatter = { - // eslint-disable-next-line @typescript-eslint/no-explicit-any - [key: string]: any; +export type DocFrontMatter = { + id?: string; + title?: string; + hide_title?: boolean; + hide_table_of_contents?: boolean; + keywords?: string[]; + image?: string; + description?: string; + slug?: string; + sidebar_label?: string; + sidebar_position?: number; + custom_edit_url?: string | null; + parse_number_prefixes?: boolean; }; export type DocMetadataBase = LastUpdateData & { @@ -200,7 +210,7 @@ export type DocMetadataBase = LastUpdateData & { // eslint-disable-next-line camelcase sidebarPosition?: number; editUrl?: string | null; - frontMatter: FrontMatter; + frontMatter: DocFrontMatter & Record; }; export type DocNavLink = { diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md index a51eaf5f74..d8051a6471 100644 --- a/website/docs/api/plugins/plugin-content-docs.md +++ b/website/docs/api/plugins/plugin-content-docs.md @@ -193,20 +193,20 @@ module.exports = { ## Markdown Frontmatter {#markdown-frontmatter} -Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side: +Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line `---` on either side: -- `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension) -- `title`: The title of your document. If this field is not present, the document's `title` will default to its `id` -- `hide_title`: Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a title at the top of your Markdown document. By default, it is `false` -- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false` -- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title` +- `id`: A unique document id. Default value: file path (including folders, without the extension) +- `title`: The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. Default value: Markdown title or doc `id` +- `hide_title`: Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. Default value: `false` +- `hide_table_of_contents`: Whether to hide the table of contents to the right. Default value: `false` +- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. Default value: doc `title` - `sidebar_position`: Permits to control the position of a doc inside the generated sidebar slice, when using `autogenerated` sidebar items. Can be Int or Float. -- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc -- `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from options fields passed to `docusaurus-plugin-content-docs` +- `parse_number_prefixes`: When a document has a number prefix (`001 - My Doc.md`, `2. MyDoc.md`...), it is automatically parsed and extracted by the plugin `numberPrefixParser`, and the number prefix is used as `sidebar_position`. Use `parse_number_prefixes: false` to disable number prefix parsing on this doc. Default value: `parse_number_prefixes` plugin option +- `custom_edit_url`: The URL for editing this document. Default value: computed using the `editUrl` plugin options - `keywords`: Keywords meta tag for the document page, for search engines -- `description`: The description of your document, which will become the `` and `` in ``, used by search engines. If this field is not present, it will default to the first line of the contents -- `image`: Cover or thumbnail image that will be used when displaying the link to your post -- `slug`: Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /` +- `description`: The description of your document, which will become the `` and `` in ``, used by search engines. Default value: the first line of Markdown content +- `image`: Cover or thumbnail image that will be used when displaying the link to your post. +- `slug`: Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. Example: