feat(v2): add editUrl option to docs plugin (#1818)

* feat(v2): add editUrl option to docs plugin

* nits

* misc(v2): nit

* misc(v2): nit

CHANGELOG-2.x.md

@@ -7,6 +7,7 @@
   - Docs sidebar can now be more than one level deep, theoretically up to infinity
   - Collapsible docs sidebar!
   - Make doc page title larger
+  - Add `editUrl` option (URL for editing) to docs plugin. If this field is set, there will be an "Edit this page" link for each doc page. Example: 'https://github.com/facebook/docusaurus/edit/master/docs'.
 - More documentation ...
 - Slight tweaks to the Blog components - blog title is larger now
 

package.json

@@ -65,10 +65,14 @@
   },
   "lint-staged": {
     "linters": {
-      "*.{js,jsx,ts,tsx}": [
+      "*.{js,jsx}": [
         "yarn lint --fix",
         "yarn prettier",
         "git add"
+      ],
+      "*.{ts,tsx}": [
+        "yarn prettier",
+        "git add"
       ]
     }
   },

packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.ts

@@ -60,4 +60,28 @@ describe('processMetadata', () => {
       description: 'This has a different permalink',
     });
   });
+
+  test('docs with editUrl', async () => {
+    const editUrl =
+      'https://github.com/facebook/docusaurus/edit/master/website/docs/';
+    const source = path.join('foo', 'baz.md');
+    const data = await processMetadata(
+      source,
+      docsDir,
+      {},
+      siteConfig,
+      pluginPath,
+      siteDir,
+      editUrl,
+    );
+    expect(data).toEqual({
+      id: 'foo/baz',
+      permalink: '/docs/foo/baz',
+      source: path.join('@site', pluginPath, source),
+      title: 'baz',
+      editUrl:
+        'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
+      description: '## Images',
+    });
+  });
 });

packages/docusaurus-plugin-content-docs-legacy/src/index.ts

@@ -62,7 +62,7 @@ export default function pluginContentDocs(
 
     // Fetches blog contents and returns metadata for the contents.
     async loadContent() {
-      const {include, routeBasePath, sidebarPath} = options;
+      const {include, routeBasePath, sidebarPath, editUrl} = options;
       const {siteConfig, siteDir} = context;
       const docsDir = contentPath;
 
@@ -93,6 +93,7 @@ export default function pluginContentDocs(
             siteConfig,
             routeBasePath,
             siteDir,
+            editUrl,
           );
           docsMetadataRaw[metadata.id] = metadata;
         }),

packages/docusaurus-plugin-content-docs-legacy/src/metadata.ts

@@ -18,6 +18,7 @@ export default async function processMetadata(
   siteConfig: Partial<DocusaurusConfig>,
   docsBasePath: string,
   siteDir: string,
+  editUrl?: string,
 ): Promise<MetadataRaw> {
   const filepath = path.join(docsDir, source);
 
@@ -82,5 +83,9 @@ export default async function processMetadata(
     }
   }
 
+  if (editUrl) {
+    metadata.editUrl = normalizeUrl([editUrl, source]);
+  }
+
   return metadata as MetadataRaw;
 }

packages/docusaurus-plugin-content-docs-legacy/src/types.ts

@@ -14,6 +14,7 @@ export interface PluginOptions {
   docItemComponent: string;
   remarkPlugins: string[];
   rehypePlugins: string[];
+  editUrl?: string;
 }
 
 export type SidebarItemDoc = {
@@ -88,6 +89,7 @@ export interface MetadataRaw extends OrderMetadata {
   source: string;
   permalink: string;
   sidebar_label?: string;
+  editUrl?: string;
   [key: string]: any;
 }
 

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

@@ -34,7 +34,7 @@ function DocLegacyItem(props) {
   const {siteConfig = {}} = useDocusaurusContext();
   const {url: siteUrl} = siteConfig;
   const {metadata, content: DocContent} = props;
-  const {description, title, permalink, image: metaImage} = metadata;
+  const {description, title, permalink, image: metaImage, editUrl} = metadata;
 
   return (
     <div>
@@ -74,7 +74,23 @@ function DocLegacyItem(props) {
                     <DocContent />
                   </div>
                 </article>
-                <div className="margin-top--xl margin-bottom--lg">
+                {editUrl && (
+                  <div className="margin-vert--xl">
+                    <div className="row">
+                      <div className="col">
+                        {editUrl && (
+                          <a
+                            href={editUrl}
+                            target="_blank"
+                            rel="noreferrer noopener">
+                            Edit this page
+                          </a>
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                )}
+                <div className="margin-vert--lg">
                   <DocLegacyPaginator metadata={metadata} />
                 </div>
               </div>

website/docs/advanced-plugins.md

@@ -144,6 +144,10 @@ module.exports = {
          * relative to site dir
          */
         path: 'docs',
+        /**
+         * URL for editing docs, example: 'https://github.com/facebook/docusaurus/edit/master/website/docs/'
+         */
+        editUrl: 'https://github.com/repo/project/website/docs/',
         /**
          * URL route for the blog section of your site
          * do not include trailing slash

website/docs/migration-from-v1-to-v2.md

@@ -265,7 +265,7 @@ module.exports = {
 
 Deprecated. Create a `CNAME` file in your `static` folder instead. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command.
 
-#### `customDocsPath`, `docsUrl`
+#### `customDocsPath`, `docsUrl`, `editUrl`
 
 Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
 
@@ -279,6 +279,8 @@ module.exports = {
         docs: {
           // Equivalent to `customDocsPath`.
           path: 'docs',
+          // Equivalent to `editUrl`
+          editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/docs/',
           // Equivalent to `docsUrl`.
           routeBasePath: 'docs',
           // Remark and Rehype plugins passed to MDX. Replaces `markdownOptions` and `markdownPlugins`.
@@ -321,7 +323,6 @@ module.exports = {
 ### Deprecated fields that may be implemented using a plugin
 
 - `enableUpdateBy`
-- `editUrl`
 - `enableUpdateTime`
 - `scripts`
 - `stylesheets`

website/docusaurus.config.js

@@ -32,6 +32,8 @@ module.exports = {
         docs: {
           path: 'docs',
           sidebarPath: require.resolve('./sidebars.js'),
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/master/website/docs/',
         },
         blog: {
           path: '../website-1.x/blog',