Skip to content

Commit

Permalink
feat(v2): add editUrl option to docs plugin (#1818)
Browse files Browse the repository at this point in the history
* feat(v2): add editUrl option to docs plugin

* nits

* misc(v2): nit

* misc(v2): nit
  • Loading branch information
endiliey authored and yangshun committed Oct 10, 2019
1 parent aba9edc commit ae678c9
Show file tree
Hide file tree
Showing 10 changed files with 66 additions and 6 deletions.
1 change: 1 addition & 0 deletions CHANGELOG-2.x.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
6 changes: 5 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
}
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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',
});
});
});
3 changes: 2 additions & 1 deletion packages/docusaurus-plugin-content-docs-legacy/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -93,6 +93,7 @@ export default function pluginContentDocs(
siteConfig,
routeBasePath,
siteDir,
editUrl,
);
docsMetadataRaw[metadata.id] = metadata;
}),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down Expand Up @@ -82,5 +83,9 @@ export default async function processMetadata(
}
}

if (editUrl) {
metadata.editUrl = normalizeUrl([editUrl, source]);
}

return metadata as MetadataRaw;
}
2 changes: 2 additions & 0 deletions packages/docusaurus-plugin-content-docs-legacy/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ export interface PluginOptions {
docItemComponent: string;
remarkPlugins: string[];
rehypePlugins: string[];
editUrl?: string;
}

export type SidebarItemDoc = {
Expand Down Expand Up @@ -88,6 +89,7 @@ export interface MetadataRaw extends OrderMetadata {
source: string;
permalink: string;
sidebar_label?: string;
editUrl?: string;
[key: string]: any;
}

Expand Down
20 changes: 18 additions & 2 deletions packages/docusaurus-theme-classic/src/theme/DocLegacyItem/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
4 changes: 4 additions & 0 deletions website/docs/advanced-plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 3 additions & 2 deletions website/docs/migration-from-v1-to-v2.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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`.
Expand Down Expand Up @@ -321,7 +323,6 @@ module.exports = {
### Deprecated fields that may be implemented using a plugin

- `enableUpdateBy`
- `editUrl`
- `enableUpdateTime`
- `scripts`
- `stylesheets`
Expand Down
2 changes: 2 additions & 0 deletions website/docusaurus.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down

0 comments on commit ae678c9

Please sign in to comment.