From 5f3541a71d6c56634a96086dc715c47a50bc973d Mon Sep 17 00:00:00 2001 From: endiliey Date: Wed, 9 Oct 2019 20:16:26 +0700 Subject: [PATCH] feat(v2): add editUrl option to docs plugin --- CHANGELOG-2.x.md | 1 + package.json | 6 ++++- .../src/__tests__/metadata.test.ts | 24 +++++++++++++++++ .../src/index.ts | 3 ++- .../src/metadata.ts | 5 ++++ .../src/types.ts | 2 ++ .../src/theme/DocLegacyItem/index.js | 11 +++++++- .../src/theme/DocLegacyItem/styles.module.css | 27 +++++++++++++++++++ website/docs/advanced-plugins.md | 4 +++ website/docs/migration-from-v1-to-v2.md | 5 ++-- website/docusaurus.config.js | 2 ++ 11 files changed, 85 insertions(+), 5 deletions(-) diff --git a/CHANGELOG-2.x.md b/CHANGELOG-2.x.md index 4c076a51f0f17..4996be73211d7 100644 --- 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 index e7353261f020c..5f8d2796babb1 100644 --- 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 index 117fe3a9d7f2e..ff3ec530d3dd7 100644 --- 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 index 790368818ae33..bb0ef63f1522e 100644 --- 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 index d148a48840e03..dddc92c9162d0 100644 --- 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, docsBasePath: string, siteDir: string, + editUrl?: string, ): Promise { 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 index 96194af2e74f2..bf29eb855312c 100644 --- 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 index b6916a87b23c1..3cee555518af4 100644 --- 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 (
@@ -66,6 +66,15 @@ function DocLegacyItem(props) {
+ {editUrl && ( + + {'Edit'} + + )}

{metadata.title}

diff --git a/packages/docusaurus-theme-classic/src/theme/DocLegacyItem/styles.module.css b/packages/docusaurus-theme-classic/src/theme/DocLegacyItem/styles.module.css index 8491fffc9634e..6f2271432b4a2 100644 --- 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; + } +} \ No newline at end of file diff --git a/website/docs/advanced-plugins.md b/website/docs/advanced-plugins.md index 288f7be52fbac..a58ec35f38600 100644 --- 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 index 18d9162f09967..707c59ac2e106 100644 --- 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 index f77c0430183d8..2d6648c7a8dfe 100644 --- 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',