SONAR-11307 Enhance embedded documentation with nav metadata

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 (
       <div>
         {node ? (
           <Link
             className={isCurrentPage || open ? 'page-indexes-link active' : 'page-indexes-link'}
             to={url}
-            title={node.frontmatter.title}>
-            {node.frontmatter.title}
+            title={linkTitle}>
+            {linkTitle}
           </Link>
         ) : (
           <a
diff --git a/server/sonar-docs/src/layouts/components/SubpageLink.js b/server/sonar-docs/src/layouts/components/SubpageLink.js
index c0027e3ed76..f3977b21be3 100644
--- a/server/sonar-docs/src/layouts/components/SubpageLink.js
+++ b/server/sonar-docs/src/layouts/components/SubpageLink.js
@@ -22,10 +22,11 @@ import Link from 'gatsby-link';
 import HeadingsLink from './HeadingsLink';
 
 export default function SubpageLink({ node, active }) {
+  const linkTitle = node.frontmatter.nav || node.frontmatter.title;
   return (
     <div>
       <Link className={active ? 'sub-menu-link active' : 'sub-menu-link'} to={node.fields.slug}>
-        {node.frontmatter.title}
+        {linkTitle}
       </Link>
     </div>
   );
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}>
-      <h3 className="list-group-item-heading">{node.title}</h3>
+      <h3 className="list-group-item-heading">{node.navTitle || node.title}</h3>
     </Link>
   );
 }
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;