Julien Lancelot 70a28fb2ec SONAR-11883 Remove redirection that was kept for old scanners | il y a 5 ans | |
---|---|---|
.. | ||
config/jest | il y a 5 ans | |
plugins/sonarsource-source-filesystem | il y a 5 ans | |
src | il y a 5 ans | |
static | il y a 5 ans | |
.eslintrc | il y a 5 ans | |
.gitignore | il y a 5 ans | |
README.md | il y a 5 ans | |
build.gradle | il y a 5 ans | |
gatsby-config.js | il y a 5 ans | |
gatsby-node.js | il y a 5 ans | |
package.json | il y a 5 ans | |
tsconfig.json | il y a 5 ans | |
yarn.lock | il y a 5 ans |
The documentation content lives in sonar-enterprise/server/sonar-docs
We use an augmented GitHub markdown syntax:
export ARTIFACTORY_PRIVATE_USERNAME=...
export ARTIFACTORY_PRIVATE_PASSWORD=...
echo $ARTIFACTORY_PRIVATE_USERNAME
echo $ARTIFACTORY_PRIVATE_PASSWORD
cd sonar-enterprise/server/sonar-web
yarn
cd ../sonar-docs
yarn
Rebuild and start your SonarQube server (yarn needs this running)
cd sonar-enterprise/
./build.sh -x test -x obfuscate
./start.sh
To start the SonarQube Embedded docs dev server on port 3000:
cd sonar-enterprise/server/sonar-web
yarn start
To start the SonarCloud Embedded docs dev server on port 3001:
cd sonar-enterprise/server/sonar-web
INSTANCE=SonarCloud PORT=3001 yarn start
You can have both SonarQube and SonarCloud embedded doc dev server running in parallel when you start them on different ports.
To start the Static docs dev server on port 8000:
cd sonar-enterprise/server/sonar-docs
yarn develop
As documentation writers there are two ways it is possible for us to break the SonarQube build
Even without spinning up servers, you can double-check that your changes won’t break the build.
Test everything
You can run all the tests, and make sure that both your markup is well-formed and your links are correct by running the build script:
cd sonar-enterprise/
./build.sh -x test -x obfuscate
Test links only
If you only want to double-check your links changes, you can
cd sonar-enterprise/server/sonar-docs
yarn jest
This will run the broken link test and stop at the first broken link it finds. Continue running this iteratively until it passes.
Always start your commit message with “DOCS”.
The convention is to start commit messages with the ticket number the changes are for. Since docs changes are often made without tickets, use “DOCS” instead.
Controlling the navigation trees of the tree instances is covered in static/README.md
All urls must end with a trailing slash (/
).
Each documentation file should contain a header at the top of the file delimited by “---” top and bottom. The header holds file metadata:
title
tag defines the title of the page.url
tag is required and defines the path at which to publish the page. Reminder: end this with a trailing slash.nav
tag is optional and controls the title of the page inside the navigation tree.Ex.:
---
title: Demo page
nav: Demo
url: /sonarcloud-pricing/
---
** Metadata conventions**
title
should come first.url
tag is required, and should start and end with ‘/’Basic syntax: @include tooltips/quality-gates/quality-gate
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 drop in “SonarQube” or “SonarCloud” as appropriate, use:
{instance}
To display/hide some other part of the content, use special comments:
<!-- 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 these comments inline:
this content is displayed on <!-- sonarcloud -->SonarCloud<!-- /sonarcloud --><!-- sonarqube -->SonarQube<!-- /sonarqube -->
Basic syntax: ## Table of Contents
Lists all h2 & h3
The resulting table of contents will also list all h1 items, but h1 is used for the page title, and by convention should not also be used further down the page.
This conditional (i.e. only if you use the tag) ToC will only appear in embedded docs. The static docs site will automatically list all h2s in a page-level ToC added to the navigation rail (left-hand side of the page)
[Link text](https://www.sonarsource.com/)
[Link text](/short-lived-branches/)
Internal SonarCloud app page: [Link text](/#sonarcloud#/onboarding)
scope: sonarcloud
), because these links are not valid on the static documentationUse this syntax to conditionally link from the embedded docs to pages within the SonarQube application. Specifically, in the static website links will be suppressed, but the link text will be shown. In the embedded documentation, administrative links will only be linked for administrative users.
[Link text](/#sonarqube#/...)
[Link text](/#sonarqube-admin#/...)
By default, single linebreaks are removed in rendering. I.e.
foo
bar
baz
Will render as
foo bar baz
To get a <br/>
effect, add 2 spaces at the end of the line
foo //<- 2 spaces
bar //<- 2 spaces
baz
Yields
foo
bar
baz
Basic syntax:
[[collapse]]
| ## Block title
| Block content
The first line of the block must be a title. You can have as many lines as you want after that.
Basic syntax: ![alt text.](/images/short-lived-branch-concept.png)
![](/images/exclamation.svg)
![](/images/info.svg)
![](/images/check.svg)
![](/images/cross.svg)
Basic syntax:
[[warning]]
| This is a **warning** message.
There must be a linebreak before the first ‘|’
There are four options:
You can also put icons inside messages:
[[danger]]
| ![](/images/cross.svg) This is a **danger** message.