From 4437a38404bd2584d4c8b232b5893f50f8ddadf5 Mon Sep 17 00:00:00 2001 From: Stas Vilchik Date: Thu, 19 Jul 2018 10:40:35 +0200 Subject: [PATCH] SONAR-11016 Add additional scope for the documentation static website (#522) --- server/sonar-docs/README.md | 37 +++++++++++++++++++ server/sonar-docs/src/templates/page.js | 4 +- .../src/main/js/apps/documentation/pages.ts | 14 ++++--- .../src/main/js/apps/documentation/utils.ts | 4 +- .../docs/__tests__/DocMarkdownBlock-test.tsx | 6 ++- .../DocMarkdownBlock-test.tsx.snap | 4 +- .../sonar-web/src/main/js/helpers/markdown.js | 20 +++++++++- 7 files changed, 76 insertions(+), 13 deletions(-) create mode 100644 server/sonar-docs/README.md diff --git a/server/sonar-docs/README.md b/server/sonar-docs/README.md new file mode 100644 index 00000000000..74de777bf87 --- /dev/null +++ b/server/sonar-docs/README.md @@ -0,0 +1,37 @@ +# sonar-docs + +## Formatting + +## Conditional Content + +With special comments you can mark a page or a part of the content to be displayed only on SonarCloud, SonarQube or the static documentation website. + +To display a page only in a certain context use the frontmatter option: + +```md +--- +scope: sonarcloud (or sonarqube, or static) +--- +``` + +To display/hide a part of the content use special comments: + +```md + +this content is displayed only on SonarCloud + + + +this content is displayed in SonarQube and in the static website + + + +this content is displayed only in the static website + +``` + +You can also use inline comments: + +```md +this content is displayed on SonarCloudSonarQube +``` diff --git a/server/sonar-docs/src/templates/page.js b/server/sonar-docs/src/templates/page.js index 052985a3d21..45040ee4807 100644 --- a/server/sonar-docs/src/templates/page.js +++ b/server/sonar-docs/src/templates/page.js @@ -26,7 +26,9 @@ export default ({ data }) => { let htmlWithInclusions = cutSonarCloudContent(page.html).replace( /\@include (.*)\<\/p\>/, (_, path) => { - const chunk = data.allMarkdownRemark.edges.find(edge => edge.node.fields.slug === path); + const chunk = data.allMarkdownRemark.edges.find( + edge => edge.node.fields && edge.node.fields.slug === path + ); return chunk ? chunk.node.html : ''; } ); 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 cb4eb61c9c1..a81c2866aad 100644 --- a/server/sonar-web/src/main/js/apps/documentation/pages.ts +++ b/server/sonar-web/src/main/js/apps/documentation/pages.ts @@ -19,7 +19,7 @@ */ import remark from 'remark'; import strip from 'strip-markdown'; -import { DocumentationEntry } from './utils'; +import { DocumentationEntry, DocumentationEntryScope } from './utils'; import * as Docs from './documentation.directory-loader'; import { separateFrontMatter, filterContent } from '../../helpers/markdown'; import { isSonarCloud } from '../../helpers/system'; @@ -39,12 +39,14 @@ export default function getPages(): DocumentationEntry[] { relativeName: file.path, title: parsed.frontmatter.title, order: Number(parsed.frontmatter.order || -1), - scope: - parsed.frontmatter.scope && parsed.frontmatter.scope.toLowerCase() === 'sonarcloud' - ? ('sonarcloud' as 'sonarcloud') - : undefined, + scope: parsed.frontmatter.scope + ? (parsed.frontmatter.scope.toLowerCase() as DocumentationEntryScope) + : undefined, text, content: file.content }; - }).filter((page: DocumentationEntry) => isSonarCloud() || page.scope !== 'sonarcloud'); + }).filter( + (page: DocumentationEntry) => + page.scope !== 'static' && (isSonarCloud() || page.scope !== 'sonarcloud') + ); } 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 854f09bce68..64ed6457367 100644 --- a/server/sonar-web/src/main/js/apps/documentation/utils.ts +++ b/server/sonar-web/src/main/js/apps/documentation/utils.ts @@ -19,11 +19,13 @@ */ import { sortBy } from 'lodash'; +export type DocumentationEntryScope = 'sonarqube' | 'sonarcloud' | 'static'; + export interface DocumentationEntry { content: string; order: number; relativeName: string; - scope?: 'sonarcloud'; + scope?: DocumentationEntryScope; text: string; title: string; } diff --git a/server/sonar-web/src/main/js/components/docs/__tests__/DocMarkdownBlock-test.tsx b/server/sonar-web/src/main/js/components/docs/__tests__/DocMarkdownBlock-test.tsx index 1dcb52eaaa2..64944d0496a 100644 --- a/server/sonar-web/src/main/js/components/docs/__tests__/DocMarkdownBlock-test.tsx +++ b/server/sonar-web/src/main/js/components/docs/__tests__/DocMarkdownBlock-test.tsx @@ -45,7 +45,7 @@ it('should use custom component for links', () => { ).toMatchSnapshot(); }); -it('should cut sonarqube/sonarcloud content', () => { +it('should cut sonarqube/sonarcloud/static content', () => { const content = ` some @@ -57,6 +57,10 @@ sonarqube sonarcloud + +static + + long diff --git a/server/sonar-web/src/main/js/components/docs/__tests__/__snapshots__/DocMarkdownBlock-test.tsx.snap b/server/sonar-web/src/main/js/components/docs/__tests__/__snapshots__/DocMarkdownBlock-test.tsx.snap index 8c2ba79743a..2245cd2300a 100644 --- a/server/sonar-web/src/main/js/components/docs/__tests__/__snapshots__/DocMarkdownBlock-test.tsx.snap +++ b/server/sonar-web/src/main/js/components/docs/__tests__/__snapshots__/DocMarkdownBlock-test.tsx.snap @@ -1,6 +1,6 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP -exports[`should cut sonarqube/sonarcloud content 1`] = ` +exports[`should cut sonarqube/sonarcloud/static content 1`] = `
@@ -44,7 +44,7 @@ exports[`should cut sonarqube/sonarcloud content 1`] = `
`; -exports[`should cut sonarqube/sonarcloud content 2`] = ` +exports[`should cut sonarqube/sonarcloud/static content 2`] = `
diff --git a/server/sonar-web/src/main/js/helpers/markdown.js b/server/sonar-web/src/main/js/helpers/markdown.js index b8991fbaa17..7f1c21325df 100644 --- a/server/sonar-web/src/main/js/helpers/markdown.js +++ b/server/sonar-web/src/main/js/helpers/markdown.js @@ -67,10 +67,26 @@ function parseFrontMatter(lines) { return data; } +/** + * @param {string} content + * @returns {string} + */ function filterContent(content) { const { isSonarCloud } = require('../helpers/system'); - const beginning = isSonarCloud() ? '' : ''; - const ending = isSonarCloud() ? '' : ''; + const contentWithoutStatic = cutConditionalContent(content, 'static'); + return isSonarCloud() + ? cutConditionalContent(contentWithoutStatic, 'sonarqube') + : cutConditionalContent(contentWithoutStatic, 'sonarcloud'); +} + +/** + * @param {string} content + * @param {string} tag + * @returns {string} + */ +function cutConditionalContent(content, tag) { + const beginning = ``; + const ending = ``; let newContent = content; let start = newContent.indexOf(beginning); -- 2.39.5