feat(v2): add 'custom_edit_url' and 'hide_title' markdown header feature (#1838)

* feat(v2): add 'custom_edit_url' and 'hide_title' markdown header feature

* nits

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. 
 

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.

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.',
+    });
+  });
 });

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 =

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;
 }
 

packages/docusaurus-theme-classic/src/theme/DocItem/index.js

@@ -74,9 +74,11 @@ function DocItem(props) {
           <div className="row">
             <div className="col">
               <div className={styles.docItemContainer}>
+                {!metadata.hide_title && (
                   <header>
                     <h1 className={styles.docTitle}>{metadata.title}</h1>
                   </header>
+                )}
                 <article>
                   <div className="markdown">
                     <DocContent />

website/docs/markdown-features.mdx

@@ -92,6 +92,28 @@ The headers are well-spaced so that the hierarchy is clear.
 
 </BrowserWindow>
 
+### 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.