Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(v2): add a banner that links to latest version of documentation #2916

Merged
merged 21 commits into from
Jun 15, 2020
Merged

feat(v2): add a banner that links to latest version of documentation #2916

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
19301c9
feat(v2): add metadata to indicate the document is old
Jun 10, 2020
fb3e311
feat(v2): add badge that links old versions to latest version
teikjun Jun 10, 2020
4358f79
feat(v2): fix test related to metadata
Jun 10, 2020
8aef76d
feat(v2): fix formatting
Jun 10, 2020
1629d92
feat(v2): fix formatting
teikjun Jun 10, 2020
3239dff
feat(v2): use Link component instead of anchor tag
teikjun Jun 10, 2020
7916468
feat(v2): add pramlink to latest docs
Jun 10, 2020
2e89fde
feat(v2): add more vibrant warning message
Jun 10, 2020
c4b1159
feat(v2): position the banner above the article
teikjun Jun 10, 2020
85ea598
feat(v2): link latest version to intro page
teikjun Jun 11, 2020
2d70251
fix(v2): fix some test cases
teikjun Jun 11, 2020
20b222f
feat(v2): fix tests
Jun 11, 2020
f4a2fcd
feat(v2): change banner to warning orange
teikjun Jun 11, 2020
32b7b07
feat(v2): compute root route from sidebar
Jun 11, 2020
711dba8
style(v2): fix formatting
teikjun Jun 11, 2020
d0f1ff3
feat(v2): use homeid if provided to compute base route
Jun 12, 2020
17c7e3a
feat(v2): rename functions and fix a corner case
Jun 12, 2020
4dfc06e
feat(v2): fix formating
Jun 12, 2020
10e7dd7
feat(v2): compute homepageurl
Jun 12, 2020
373baf5
style(v2): improve code quality
teikjun Jun 14, 2020
12ef010
style(v2): unbold fullstop for consistency
teikjun Jun 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/__tests__/index.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ describe('simple website', () => {
source: path.join('@site', pluginPath, 'hello.md'),
title: 'Hello, World !',
description: 'Hi, Endilie here :)',
isOld: false,
});

expect(docsMetadata['foo/bar']).toEqual({
Expand All @@ -176,6 +177,7 @@ describe('simple website', () => {
source: path.join('@site', pluginPath, 'foo', 'bar.md'),
title: 'Bar',
description: 'This is custom description',
isOld: false,
});

expect(docsSidebars).toMatchSnapshot();
Expand Down Expand Up @@ -304,6 +306,7 @@ describe('versioned website', () => {
title: 'hello',
permalink: '/docs/next/hello',
},
isOld: false,
});
expect(docsMetadata['hello']).toEqual({
id: 'hello',
Expand All @@ -317,6 +320,7 @@ describe('versioned website', () => {
title: 'bar',
permalink: '/docs/next/foo/barSlug',
},
isOld: false,
});
expect(docsMetadata['version-1.0.1/hello']).toEqual({
id: 'version-1.0.1/hello',
Expand All @@ -335,6 +339,7 @@ describe('versioned website', () => {
title: 'bar',
permalink: '/docs/foo/bar',
},
isOld: false,
});
expect(docsMetadata['version-1.0.0/foo/baz']).toEqual({
id: 'version-1.0.0/foo/baz',
Expand All @@ -359,6 +364,7 @@ describe('versioned website', () => {
title: 'bar',
permalink: '/docs/1.0.0/foo/barSlug',
},
isOld: true,
});

expect(docsSidebars).toMatchSnapshot('all sidebars');
Expand Down
12 changes: 12 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/__tests__/metadata.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,13 +50,15 @@ describe('simple site', () => {
source: path.join('@site', routeBasePath, sourceA),
title: 'Bar',
description: 'This is custom description',
isOld: false,
});
expect(dataB).toEqual({
id: 'hello',
permalink: '/docs/hello',
source: path.join('@site', routeBasePath, sourceB),
title: 'Hello, World !',
description: `Hi, Endilie here :)`,
isOld: false,
});
});

Expand Down Expand Up @@ -85,6 +87,7 @@ describe('simple site', () => {
editUrl:
'https://github.com/facebook/docusaurus/edit/master/website/docs/foo/baz.md',
description: 'Images',
isOld: false,
});
});

Expand All @@ -109,6 +112,7 @@ describe('simple site', () => {
title: 'lorem',
editUrl: 'https://github.com/customUrl/docs/lorem.md',
description: 'Lorem ipsum.',
isOld: false,
});

// unrelated frontmatter is not part of metadata
Expand Down Expand Up @@ -140,6 +144,7 @@ describe('simple site', () => {
description: 'Lorem ipsum.',
lastUpdatedAt: 1539502055,
lastUpdatedBy: 'Author',
isOld: false,
});
});

Expand Down Expand Up @@ -168,6 +173,7 @@ describe('simple site', () => {
description: 'Lorem ipsum.',
lastUpdatedAt: 1539502055,
lastUpdatedBy: 'Author',
isOld: false,
});
});

Expand Down Expand Up @@ -249,6 +255,7 @@ describe('versioned site', () => {
title: 'bar',
description: 'This is next version of bar.',
version: 'next',
isOld: false,
});
expect(dataB).toEqual({
id: 'hello',
Expand All @@ -257,6 +264,7 @@ describe('versioned site', () => {
title: 'hello',
description: 'Hello next !',
version: 'next',
isOld: false,
});
});

Expand Down Expand Up @@ -307,6 +315,7 @@ describe('versioned site', () => {
title: 'bar',
description: 'Bar 1.0.0 !',
version: '1.0.0',
isOld: true,
});
expect(dataB).toEqual({
id: 'version-1.0.0/hello',
Expand All @@ -315,6 +324,7 @@ describe('versioned site', () => {
title: 'hello',
description: 'Hello 1.0.0 !',
version: '1.0.0',
isOld: true,
});
expect(dataC).toEqual({
id: 'version-1.0.1/foo/bar',
Expand All @@ -323,6 +333,7 @@ describe('versioned site', () => {
title: 'bar',
description: 'Bar 1.0.1 !',
version: '1.0.1',
isOld: false,
});
expect(dataD).toEqual({
id: 'version-1.0.1/hello',
Expand All @@ -331,6 +342,7 @@ describe('versioned site', () => {
title: 'hello',
description: 'Hello 1.0.1 !',
version: '1.0.1',
isOld: false,
});
});
});
6 changes: 6 additions & 0 deletions packages/docusaurus-plugin-content-docs/src/metadata.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,11 @@ export default async function processMetadata({
const versionPath =
version && version !== versioning.latestVersion ? version : '';

const isOld =
version && version !== 'next'
? version !== versioning.latestVersion
: false;

const relativePath = path.relative(siteDir, filePath);

const docsEditUrl = getEditUrl(relativePath, editUrl);
Expand Down Expand Up @@ -145,6 +150,7 @@ export default async function processMetadata({
lastUpdatedBy,
lastUpdatedAt,
sidebar_label,
isOld,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should rather try to compute, for each doc, what's the permalink to the latest version of the same doc.

maybe we need a property like latestPermalink

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some docs may get deleted in newer version of doc

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In such case latestPermalink would be undefined, and you wouldn't add the link?

Ah that's right, you want to link to the docs root, not necessarily the same doc in another version, so this is probably overkill.

};

return metadata;
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-plugin-content-docs/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,7 @@ export interface MetadataRaw extends LastUpdateData {
sidebar_label?: string;
editUrl?: string;
version?: string;
isOld?: boolean;
}

export interface Paginator {
Expand Down
7 changes: 7 additions & 0 deletions packages/docusaurus-theme-classic/src/theme/DocItem/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import useBaseUrl from '@docusaurus/useBaseUrl';
import DocPaginator from '@theme/DocPaginator';
import useTOCHighlight from '@theme/hooks/useTOCHighlight';
import Link from '@docusaurus/Link';

import clsx from 'clsx';
import styles from './styles.module.css';
Expand Down Expand Up @@ -68,6 +69,7 @@ function DocItem(props) {
lastUpdatedAt,
lastUpdatedBy,
version,
isOld,
} = metadata;
const {
frontMatter: {
Expand Down Expand Up @@ -115,6 +117,11 @@ function DocItem(props) {
<span className="badge badge--secondary">
Version: {version}
</span>
{isOld ? (
<span className="badge badge--secondary margin-horiz--xs">
<Link to="/docs"> Go to latest version </Link>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The /docs url is configurable, so it's not a good idea to hardcode the link to /docs here, + there's no guarantee that the user used the docs "homePageId" feature.

See https://v2.docusaurus.io/docs/docs-introduction/#docs-only-mode

</span>
) : null}
</div>
)}
{!hideTitle && (
Expand Down