diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md index c7d503afa1..ad510a4d58 100644 --- a/CHANGELOG-2.x.md +++ b/CHANGELOG-2.x.md @@ -2,7 +2,8 @@ ## Unreleased -- Add `@theme/Tabs` which can be used to implement multi-language code tabs +- Add `@theme/Tabs` which can be used to implement multi-language code tabs. +- Implement `custom_edit_url` and `hide_title` markdown header for docusaurus v1 feature parity. - Reduce memory usage and slightly faster production build. - Misc dependency upgrades. diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md new file mode 100644 index 0000000000..15589144c4 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/__fixtures__/website/docs/lorem.md @@ -0,0 +1,6 @@ +--- +id: lorem +custom_edit_url: https://github.com/customUrl/docs/lorem.md +--- + +Lorem ipsum. \ No newline at end of file diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts index c2d9c0818d..1a6ca22a17 100644 --- a/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts +++ b/packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts @@ -101,4 +101,25 @@ describe('processMetadata', () => { description: '## Images', }); }); + + test('docs with custom editUrl', async () => { + const source = 'lorem.md'; + const data = await processMetadata({ + source, + docsDir, + order: {}, + siteConfig, + docsBasePath: pluginPath, + siteDir, + }); + + expect(data).toEqual({ + id: 'lorem', + permalink: '/docs/lorem', + source: path.join('@site', pluginPath, source), + title: 'lorem', + editUrl: 'https://github.com/customUrl/docs/lorem.md', + description: 'Lorem ipsum.', + }); + }); }); diff --git a/packages/docusaurus-plugin-content-docs/src/metadata.ts b/packages/docusaurus-plugin-content-docs/src/metadata.ts index 718d0e45ae..e1bfb64f4c 100644 --- a/packages/docusaurus-plugin-content-docs/src/metadata.ts +++ b/packages/docusaurus-plugin-content-docs/src/metadata.ts @@ -103,6 +103,11 @@ export default async function processMetadata({ metadata.editUrl = normalizeUrl([editUrl, source]); } + if (metadata.custom_edit_url) { + metadata.editUrl = metadata.custom_edit_url; + delete metadata.custom_edit_url; + } + if (showLastUpdateAuthor || showLastUpdateTime) { // Use fake data in dev for faster development const fileLastUpdateData = diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 23ab9b380d..faaf3fb7be 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -94,6 +94,7 @@ export interface MetadataRaw extends OrderMetadata { editUrl?: string; lastUpdatedAt?: number; lastUpdatedBy?: string; + hide_title?: boolean; [key: string]: any; } diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js index 3e808adccf..0b8c7fd54d 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.js +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.js @@ -74,9 +74,11 @@ function DocItem(props) {
-
-

{metadata.title}

-
+ {!metadata.hide_title && ( +
+

{metadata.title}

+
+ )}
diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index 1fae5751fc..4847e65dd2 100644 --- a/website/docs/markdown-features.mdx +++ b/website/docs/markdown-features.mdx @@ -92,6 +92,28 @@ The headers are well-spaced so that the hierarchy is clear. +### Markdown Headers + +Documents use the following markdown header fields that are 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. 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`. +- `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`. + +Example: + +```md +--- +id: doc-markdown +title: Markdown Features +sidebar_label: Markdown :) +custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md +--- + +``` + ### Embedding React components Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.