SONAR-11016 Add additional scope for the documentation static website (#522)

diff --git a/server/sonar-docs/README.md b/server/sonar-docs/README.md
new file mode 100644 (file)
index 0000000..74de777
--- /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
+<!-- sonarcloud -->
+this content is displayed only on SonarCloud
+<!-- /sonarcloud -->
+
+<!-- sonarqube -->
+this content is displayed in SonarQube and in the static website
+<!-- /sonarqube -->
+
+<!-- static -->
+this content is displayed only in the static website
+<!-- /static -->
+```
+
+You can also use inline comments:
+
+```md
+this content is displayed on <!-- sonarcloud -->SonarCloud<!-- /sonarcloud --><!-- sonarqube -->SonarQube<!-- /sonarqube -->
+```

diff --git a/server/sonar-docs/src/templates/page.js b/server/sonar-docs/src/templates/page.js
index 052985a3d21eec7165436b4ad6a56660d39650ad..45040ee4807c009b2372eff634cf9d3b87b58dd2 100644 (file)
--- 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(
     /\<p\>@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 cb4eb61c9c1db7df312a238def3a1c1a7da739da..a81c2866aad56d2f1715d697c580cc88e45a0135 100644 (file)
--- 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 854f09bce682540ed55a31fb543b4b9c6c6bd3d3..64ed645736707974301da0bc219c4ee6d0e94a0e 100644 (file)
--- 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 1dcb52eaaa243f3ca7dc256e47c17cbdc0f34db6..64944d0496a9552062524c75ad0e74c778772b3d 100644 (file)
--- 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
 <!-- /sonarcloud -->
 
+<!-- static -->
+static
+<!-- /static -->
+
 <!-- sonarqube -->
   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 8c2ba79743ae53d98ec575a694fa39fa41525887..2245cd2300a15c055f19fdc3fe2ee6812396611d 100644 (file)
--- 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`] = `
 <div
   className="markdown"
 >
@@ -44,7 +44,7 @@ exports[`should cut sonarqube/sonarcloud content 1`] = `
 </div>
 `;
 
-exports[`should cut sonarqube/sonarcloud content 2`] = `
+exports[`should cut sonarqube/sonarcloud/static content 2`] = `
 <div
   className="markdown"
 >

diff --git a/server/sonar-web/src/main/js/helpers/markdown.js b/server/sonar-web/src/main/js/helpers/markdown.js
index b8991fbaa17aabfd6be913dc6b5cc0b5ca3d6985..7f1c21325dfd44c1c152ec6c93c2b7896f0a2b42 100644 (file)
--- 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() ? '<!-- sonarqube -->' : '<!-- sonarcloud -->';
-  const ending = isSonarCloud() ? '<!-- /sonarqube -->' : '<!-- /sonarcloud -->';
+  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 = `<!-- ${tag} -->`;
+  const ending = `<!-- /${tag} -->`;
 
   let newContent = content;
   let start = newContent.indexOf(beginning);