From d55090a928fdedad0f88d46fcf6976f8db796bf7 Mon Sep 17 00:00:00 2001 From: Pascal Mugnier Date: Thu, 25 Oct 2018 14:27:13 +0200 Subject: [PATCH] SONAR-11307 Enhance embedded documentation with nav metadata --- .../sonar-docs/src/__tests__/BrokenLinkSafetyNet.test.js | 9 +++++++++ server/sonar-docs/src/layouts/components/CategoryLink.js | 5 +++-- server/sonar-docs/src/layouts/components/SubpageLink.js | 3 ++- server/sonar-docs/src/layouts/index.js | 1 + server/sonar-docs/src/pages/404.md | 1 + .../main/js/apps/documentation/components/MenuItem.tsx | 2 +- .../documentation/components/__tests__/Menu-test.tsx | 2 +- .../components/__tests__/MenuBlock-test.tsx | 2 ++ .../components/__tests__/SearchResultEntry-test.tsx | 3 ++- .../components/__tests__/SearchResults-test.tsx | 2 +- .../documentation/components/__tests__/Sidebar-test.tsx | 2 +- .../__tests__/__snapshots__/Menu-test.tsx.snap | 3 +++ .../__tests__/__snapshots__/MenuBlock-test.tsx.snap | 2 ++ .../__snapshots__/SearchResultEntry-test.tsx.snap | 2 ++ .../__tests__/__snapshots__/SearchResults-test.tsx.snap | 2 ++ .../__tests__/__snapshots__/Sidebar-test.tsx.snap | 4 ++++ server/sonar-web/src/main/js/apps/documentation/pages.ts | 1 + server/sonar-web/src/main/js/apps/documentation/utils.ts | 1 + 18 files changed, 39 insertions(+), 8 deletions(-) diff --git a/server/sonar-docs/src/__tests__/BrokenLinkSafetyNet.test.js b/server/sonar-docs/src/__tests__/BrokenLinkSafetyNet.test.js index 91a47bc91a4..fdf2a42ad37 100644 --- a/server/sonar-docs/src/__tests__/BrokenLinkSafetyNet.test.js +++ b/server/sonar-docs/src/__tests__/BrokenLinkSafetyNet.test.js @@ -33,6 +33,15 @@ beforeAll(async () => { }); }); +it('should have at least one instance of all possible frontmatter fields', () => { + let pageWithTitle = parsedFiles.find(file => file.frontmatter.title !== undefined); + let pageWithNav = parsedFiles.find(file => file.frontmatter.nav !== undefined); + let pageWithUrl = parsedFiles.find(file => file.frontmatter.url !== undefined); + expect(pageWithTitle).toBeDefined(); + expect(pageWithNav).toBeDefined(); + expect(pageWithUrl).toBeDefined(); +}); + it('should have valid links in trees files', () => { const trees = [ 'SonarCloudNavigationTree.json', diff --git a/server/sonar-docs/src/layouts/components/CategoryLink.js b/server/sonar-docs/src/layouts/components/CategoryLink.js index aa3ef073347..de708652ad0 100644 --- a/server/sonar-docs/src/layouts/components/CategoryLink.js +++ b/server/sonar-docs/src/layouts/components/CategoryLink.js @@ -41,14 +41,15 @@ export default class CategoryLink extends React.PureComponent { const prefix = process.env.GATSBY_DOCS_VERSION ? '/' + process.env.GATSBY_DOCS_VERSION : ''; const url = node ? node.frontmatter.url || node.fields.slug : ''; const isCurrentPage = location.pathname === prefix + url; + const linkTitle = node ? node.frontmatter.nav || node.frontmatter.title : ''; return (
{node ? ( - {node.frontmatter.title} + title={linkTitle}> + {linkTitle} ) : ( - {node.frontmatter.title} + {linkTitle}
); diff --git a/server/sonar-docs/src/layouts/index.js b/server/sonar-docs/src/layouts/index.js index a65714c59c2..fe7a97cf4c5 100644 --- a/server/sonar-docs/src/layouts/index.js +++ b/server/sonar-docs/src/layouts/index.js @@ -69,6 +69,7 @@ export const query = graphql` } frontmatter { title + nav url } fields { diff --git a/server/sonar-docs/src/pages/404.md b/server/sonar-docs/src/pages/404.md index d6a0f85fd7e..ef227477acb 100644 --- a/server/sonar-docs/src/pages/404.md +++ b/server/sonar-docs/src/pages/404.md @@ -1,5 +1,6 @@ --- title: Page not found +nav: Not found url: /404/ --- diff --git a/server/sonar-web/src/main/js/apps/documentation/components/MenuItem.tsx b/server/sonar-web/src/main/js/apps/documentation/components/MenuItem.tsx index 0b67f4d7045..9c375d5f3e7 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/MenuItem.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/MenuItem.tsx @@ -40,7 +40,7 @@ export function MenuItem({ indent, node, splat }: Props) { key={node.url} style={{ paddingLeft: indent ? 31 : 10 }} to={'/documentation' + node.url}> -

{node.title}

+

{node.navTitle || node.title}

); } diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Menu-test.tsx b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Menu-test.tsx index 1985bc439f6..b0cddf170b3 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Menu-test.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Menu-test.tsx @@ -22,7 +22,7 @@ import { shallow } from 'enzyme'; import Menu from '../Menu'; function createPage(title: string, relativeName: string, text = '') { - return { relativeName, url: '/' + relativeName, title, text, content: text }; + return { relativeName, url: '/' + relativeName, title, navTitle: undefined, text, content: text }; } const pages = [ diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/MenuBlock-test.tsx b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/MenuBlock-test.tsx index 9dcfe468335..0c09a83d9e6 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/MenuBlock-test.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/MenuBlock-test.tsx @@ -32,6 +32,7 @@ const pages = [ relativeName: '/bar/', text: 'bar', title: 'Bar', + navTitle: undefined, url: '/bar/' }, { @@ -39,6 +40,7 @@ const pages = [ relativeName: '/baz/', text: 'baz', title: 'baz', + navTitle: 'baznav', url: '/baz/' } ]; diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResultEntry-test.tsx b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResultEntry-test.tsx index f38330cb585..abac5820709 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResultEntry-test.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResultEntry-test.tsx @@ -30,7 +30,8 @@ const page = { relativeName: 'foo/bar', url: '/foo/bar', text: 'Foobar is a universal variable understood to represent whatever is being discussed.', - title: 'Foobar' + title: 'Foobar', + navTitle: undefined }; describe('SearchResultEntry', () => { diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResults-test.tsx b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResults-test.tsx index be38eb5a2f6..4c5dc23c5df 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResults-test.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/SearchResults-test.tsx @@ -37,7 +37,7 @@ jest.mock('lunr', () => ({ })); function createPage(title: string, relativeName: string, text = '') { - return { relativeName, url: '/' + relativeName, title, text, content: text }; + return { relativeName, url: '/' + relativeName, title, navTitle: undefined, text, content: text }; } const pages = [ diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Sidebar-test.tsx b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Sidebar-test.tsx index ab41a1a9afe..a30516ef711 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Sidebar-test.tsx +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/Sidebar-test.tsx @@ -22,7 +22,7 @@ import { shallow } from 'enzyme'; import Sidebar from '../Sidebar'; function createPage(title: string, relativeName: string, text = '') { - return { relativeName, url: '/' + relativeName, title, text, content: text }; + return { relativeName, url: '/' + relativeName, title, navTitle: undefined, text, content: text }; } const pages = [ diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Menu-test.tsx.snap b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Menu-test.tsx.snap index 469a3f41a6d..ed2f0e728ea 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Menu-test.tsx.snap +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Menu-test.tsx.snap @@ -19,6 +19,7 @@ Array [ Array [ Object { "content": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.", + "navTitle": undefined, "relativeName": "lorem/index", "text": "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book.", "title": "Lorem Ipsum", @@ -26,6 +27,7 @@ Array [ }, Object { "content": "Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words.", + "navTitle": undefined, "relativeName": "lorem/origin", "text": "Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words.", "title": "Where does it come from?", @@ -33,6 +35,7 @@ Array [ }, Object { "content": "Foobar is a universal variable understood to represent whatever is being discussed.", + "navTitle": undefined, "relativeName": "foobar", "text": "Foobar is a universal variable understood to represent whatever is being discussed.", "title": "Where does Foobar come from?", diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/MenuBlock-test.tsx.snap b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/MenuBlock-test.tsx.snap index 9f08ac7b98b..0ee9f2fbead 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/MenuBlock-test.tsx.snap +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/MenuBlock-test.tsx.snap @@ -43,6 +43,7 @@ exports[`should render an opened menu block 1`] = ` node={ Object { "content": "bar", + "navTitle": undefined, "relativeName": "/bar/", "text": "bar", "title": "Bar", @@ -57,6 +58,7 @@ exports[`should render an opened menu block 1`] = ` node={ Object { "content": "baz", + "navTitle": "baznav", "relativeName": "/baz/", "text": "baz", "title": "baz", diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResultEntry-test.tsx.snap b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResultEntry-test.tsx.snap index cc19cf2f4ff..40818733fe7 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResultEntry-test.tsx.snap +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResultEntry-test.tsx.snap @@ -14,6 +14,7 @@ exports[`SearchResultEntry should render 1`] = ` "longestTerm": "", "page": Object { "content": "", + "navTitle": undefined, "relativeName": "foo/bar", "text": "Foobar is a universal variable understood to represent whatever is being discussed.", "title": "Foobar", @@ -29,6 +30,7 @@ exports[`SearchResultEntry should render 1`] = ` "longestTerm": "", "page": Object { "content": "", + "navTitle": undefined, "relativeName": "foo/bar", "text": "Foobar is a universal variable understood to represent whatever is being discussed.", "title": "Foobar", diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResults-test.tsx.snap b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResults-test.tsx.snap index 2abdbd1e2ca..4a79799119b 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResults-test.tsx.snap +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/SearchResults-test.tsx.snap @@ -24,6 +24,7 @@ exports[`should search 1`] = ` "longestTerm": "from", "page": Object { "content": "Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words.", + "navTitle": undefined, "relativeName": "lorem/origin", "text": "Contrary to popular belief, Lorem Ipsum is not simply random text. It has roots in a piece of classical Latin literature from 45 BC, making it over 2000 years old. Richard McClintock, a Latin professor at Hampden-Sydney College in Virginia, looked up one of the more obscure Latin words.", "title": "Where does it come from?", @@ -48,6 +49,7 @@ exports[`should search 1`] = ` "longestTerm": "from", "page": Object { "content": "Foobar is a universal variable understood to represent whatever is being discussed.", + "navTitle": undefined, "relativeName": "foobar", "text": "Foobar is a universal variable understood to represent whatever is being discussed.", "title": "Where does Foobar come from?", diff --git a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Sidebar-test.tsx.snap b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Sidebar-test.tsx.snap index 7e7444143b4..0b051b98546 100644 --- a/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Sidebar-test.tsx.snap +++ b/server/sonar-web/src/main/js/apps/documentation/components/__tests__/__snapshots__/Sidebar-test.tsx.snap @@ -31,6 +31,7 @@ exports[`should render menu 1`] = ` Array [ Object { "content": "", + "navTitle": undefined, "relativeName": "lorem/index", "text": "", "title": "Lorem Ipsum", @@ -38,6 +39,7 @@ exports[`should render menu 1`] = ` }, Object { "content": "", + "navTitle": undefined, "relativeName": "foobar", "text": "", "title": "Where does Foobar come from?", @@ -83,6 +85,7 @@ exports[`should search 1`] = ` Array [ Object { "content": "", + "navTitle": undefined, "relativeName": "lorem/index", "text": "", "title": "Lorem Ipsum", @@ -90,6 +93,7 @@ exports[`should search 1`] = ` }, Object { "content": "", + "navTitle": undefined, "relativeName": "foobar", "text": "", "title": "Where does Foobar come from?", diff --git a/server/sonar-web/src/main/js/apps/documentation/pages.ts b/server/sonar-web/src/main/js/apps/documentation/pages.ts index 7aea76e867c..4c94af0c3a0 100644 --- a/server/sonar-web/src/main/js/apps/documentation/pages.ts +++ b/server/sonar-web/src/main/js/apps/documentation/pages.ts @@ -33,6 +33,7 @@ export default function getPages(): DocumentationEntry[] { relativeName: file.path, url: parsed.frontmatter.url || `/${file.path}`, title: parsed.frontmatter.title, + navTitle: parsed.frontmatter.nav || undefined, order: Number(parsed.frontmatter.order || -1), scope: parsed.frontmatter.scope ? (parsed.frontmatter.scope.toLowerCase() as DocumentationEntryScope) diff --git a/server/sonar-web/src/main/js/apps/documentation/utils.ts b/server/sonar-web/src/main/js/apps/documentation/utils.ts index 3c08b6a26b4..5f82f3dce9a 100644 --- a/server/sonar-web/src/main/js/apps/documentation/utils.ts +++ b/server/sonar-web/src/main/js/apps/documentation/utils.ts @@ -34,6 +34,7 @@ export interface DocsNavigationExternalLink { export interface DocumentationEntry { content: string; relativeName: string; + navTitle: string | undefined; text: string; title: string; url: string; -- 2.39.5