feat(v2): add editUrl option to docs plugin

facebook · Oct 9, 2019 · 5f3541a · 5f3541a
1 parent e7ba8af
commit 5f3541a
Show file tree

Hide file tree

Showing 11 changed files with 85 additions and 5 deletions.
diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md
@@ -3,6 +3,7 @@
 ## Unreleased
 - Docs plugin is rewritten in TypeScript
 - Docs sidebar can now be more than one level deep, theoretically up to infinity.
+- Add `editUrl` option (URL for editing) to docs plugin. If this field is set, there will be "Edit" button for each document page. Example: 'https://github.com/facebook/docusaurus/edit/master/docs'.
 - more documentation ...
 
 ## 2.0.0-alpha.25

diff --git a/package.json b/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"
       ]
     }
   },

diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/__tests__/metadata.test.ts b/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',
+    });
+  });
 });
diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/index.ts b/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;
         }),

diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/metadata.ts b/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;
 }
diff --git a/packages/docusaurus-plugin-content-docs-legacy/src/types.ts b/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;
 }
 

diff --git a/packages/docusaurus-theme-classic/src/theme/DocLegacyItem/index.js b/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>
@@ -66,6 +66,15 @@ function DocLegacyItem(props) {
           <div className="col">
             <div className={styles.docItemContainer}>
               <header>
+                {editUrl && (
+                  <a
+                    className={styles.editButton}
+                    href={editUrl}
+                    target="_blank"
+                    rel="noreferrer noopener">
+                    {'Edit'}
+                  </a>
+                )}
                 <h1 className="margin-bottom--lg">{metadata.title}</h1>
               </header>
               <article>

diff --git a/packages/docusaurus-theme-classic/src/theme/DocLegacyItem/styles.module.css b/packages/docusaurus-theme-classic/src/theme/DocLegacyItem/styles.module.css
@@ -23,3 +23,30 @@
     display: none;
   }
 }
+
+.editButton {
+  float: right;
+  margin-top: 5px;
+  display: flex;
+  align-items: center;
+  font-size: 14px;
+  font-weight: 500;
+  line-height: 1em;
+  height: 30px;
+  border-width: 1px;
+  border-style: solid;
+  border-radius: 3px;
+  transition: all 0.2s ease-out 0s;
+  text-decoration: none !important;
+  padding: 5px 16px;
+}
+
+.editButton:hover {
+  color: var(--ifm-font-base-color);
+}
+
+@media only screen and (max-width: 997px) {
+  .editButton {
+    display: none;
+  }
+}
diff --git a/website/docs/advanced-plugins.md b/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: '',
         /**
          * URL route for the blog section of your site
          * do not include trailing slash

diff --git a/website/docs/migration-from-v1-to-v2.md b/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`

diff --git a/website/docusaurus.config.js b/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',