This is the multi-page printable view of this section. Click here to print.
This site is built using Hugo with the Docsy Hugo theme. The content is pre-dominantly authored in Markdown with some Hugo shortcodes.
In order to build and contribute to the documentation you will need the following installed:
Docker or Docker Desktop is required as all the build steps are performed in docker containers to ensure a consistent and known build environment. It also ensures that the local build environment matches that used in GitHub actions.
docker-buildx is a plugin for docker that allows caching of the docker images to speed up the build process.
This may be installed by your package manager when you install docker or Docker Desktop, or you may need to install it separately.
You can confirm you have buildx by executing the following command which should give you output similar to this:
It is possible to build the docs without docker but you would need to install all the other dependencies that are provided in the docker images, e.g. java, plantuml, puppeteer, hugo, npm, html2canvas, jspdf, graphviz etc.
It is assumed that you have a reasonable understanding of how to use Git and Github, specifically:
The git repository for this site is stroom-docs (external link).
stroom-docs uses the Docsy theme (themes/docsy/) via a Go module so the theme will be pulled in when Hugo is first run.
Unless you are a committer on the gchq/stroom-docs repository, you will need to fork this repository into your own Github account.
You can then clone your fork of the repository like so (in this example it is assumed your Github username is jbloggs):
You now need to configure the clone of your fork with details of the gchq/stroom-docs upstream, which will allow you to pull changes from it.
There is a version of the documentation for each minor Stroom version (see Stroom Versions.
Before you start editing/viewing the documentation you need to be working from the correct branch of the Git repository.
If for example you are adding some content that is applicable to Stroom v7.0 then you need to checkout branch 7.0.
If you are making changes to the documentation then the recommended working practice is to always make changes on a feature branch.
A feature branch would typically contain all commits/changes relating to a single feature, e.g. the addition of a new section, or updating the documentation for a specific change in Stroom.
Having only these changes on a branch makes it easy to merge them into the release branch (e.g. 7.0) or to just delete the branch if they are no longer needed.
A feature branch would typically be merged into the appropriate release branch by creating a pull request in GitHub.
Assuming you have checked out the desired release branch that you would like your changes to ultimately be merged into, do something like the following to create a feature branch (where add-properties-section is the name of your branch):
This will create the named branch and check it out in one step.
stroom-docs makes used of
PlantUML
for a lot of its diagrams.
These are stored in the repository as .puml text files.
In order that they can be rendered in the site they need to be converted into SVGs first.
.puml files and converted at build time.
To convert all .puml files into sibling .puml.svg files do the following:
This command will find all .puml files (in content/ and assets/) and convert each one to SVG.
It only needs to be run on first clone of the repo or when .puml files are added/changed.
The generated .puml.svg files are ignored by git.
This command will be run as part of the GitHub Actions automated build.
If runInPumlDocker.sh SVG is not run having added links to PlantUML images in the documentation, then when you build or serve the site you will see errors like this:
Error: Error building site: "/builder/shared/content/en/docs/user-guide/concepts/streams.md:57:1":
failed to render shortcode "image":
failed to process shortcode: "/builder/shared/layouts/shortcodes/image.html:54:21":
execute of template failed: template: shortcodes/image.html:54:21:
executing "shortcodes/image.html" at <$image.Name>: nil pointer evaluating resource.Resource.Name
/builder/shared/, so if you see this path mentioned in the logs this is referring to your local repository.
The documentation can be built and served locally while developing it. To build and serve the site run
This uses Hugo to build the site in memory and then serve it from a local web server. When any source files are changed or added Hugo will detect this and rebuild the site as required, including automatically refreshing the browser page to update the rendered view.
Once the server is running the site is available at localhost:1313.
To perform a full build of the static site run:
This will generate all the static content and place it in public/.
Every page has a Print entire section link that will display a printable view of that section and its children.
In addition to this the GitHub Actions we generate a PDF of the docs section and all its children, i.e. all of the documentation (but not News/Releases or Community) in one PDF.
This makes the documentation available for offline use.
To test the PDF generation do:
The Docsy theme is a dependency of this Hugo site. See Update the Hugo Docsy Module for details on how to update the version of the Docsy theme.
In those instructions when it says to run a hugo command you need to do it from within the hugo docker container.
This will give you a bash prompt inside the container that has the hugo binary available.
The container has access to your local stroom-docs repository (from where you ran runInHugoDocker.sh) and the initial directory is the root of the repository.
Inside the container the root of the repository is mounted as /builder/shared.
To leave the container’s shell type exit.
Alternatively you can run a single command directly, e.g. to update Docsy to 0.6.0 do:
The Docsy theme supports site versioning so that multiple versions of the site/documentation can exist and link between each other.
For this documentation site, each version of the site is tied to a minor release of Stroom, e.g. 7.0, 7.1, 7.2, 8.0 etc.
Each Stroom version is represented by a git branch with the same name.
There is an additional git branch legacy that is for all Stroom versions prior to 7.0 and will be removed once the versions prior to 7.0 are no longer supported.
Documentation changes for an as yet unreleased Stroom version would be performed on the master branch.
When the combined site is built, each version will exist within a directory as siblings of each other, i.e.
/7.0/
/7.1/
/7.2/
/8.0/
/legacy/
The master branch is NOT published to GitHub Pages or included in the release artefacts.
To configure each version of the site so that it knows what version it is and what the other versions are you need to edit config.toml.
This needs to be done on each branch in a way that is appropriate to each branch.
If a change needs to be applied to all branches then it is best to make it in the oldest branch for which the documentation is published, and then merge the changes the changes up the chain, e.g. legacy => 7.0 => 7.1 => 7.2 => 8.0 => master.
The following config properties needed to be amended on each branch. This example is from the 7.1 branch and is based on there being versions legacy, 7.0 and 7.1, with 7.1 being the latest.
[params]
# Menu title if your navbar has a versions selector
# to access old versions of your site.
version_menu = "Stroom Version (7.1)"
# If true, displays a banner on each page warning that
# it is an old version. Set this to true on each git branch
# of stroom-docs that is not the latest release branch
archived_version = false
# Used in the banner on each archived page.
# Must match the value in brackets in "version_menu" above
version = "7.1"
# A link to latest version of the docs. Used in the
# "version-banner" partial to point people to the main
# doc site.
url_latest_version = "/../7.1"
# The name of the github branch that this version of the
# documentation lives on. Used for the github links in the
# top of the right hand sidebar. Should match the last part
# of url_latest_version.
github_branch = "7.1"
# A set of all the versions that are available.
[[params.versions]]
version = "7.1"
url = "/../7.1"
[[params.versions]]
version = "7.0"
url = "/../7.0"
[[params.versions]]
version = "Legacy"
url = "/../legacy"
[params]
# Menu title if your navbar has a versions selector
# to access old versions of your site.
version_menu = "Stroom Version (7.0)"
# If true, displays a banner on each page warning that
# it is an old version. Set this to true on each git branch
# of stroom-docs that is not the latest release branch
archived_version = true
# Used in the banner on each archived page.
# Must match the value in brackets in "version_menu" above
version = "7.0"
# A link to latest version of the docs. Used in the
# "version-banner" partial to point people to the main
# doc site.
url_latest_version = "/../7.1"
# The name of the github branch that this version of the
# documentation lives on. Used for the github links in the
# top of the right hand sidebar. Should match the last part
# of url_latest_version.
github_branch = "7.0"
# A set of all the versions that are available.
[[params.versions]]
version = "7.1"
url = "/../7.1"
[[params.versions]]
version = "7.0"
url = "/../7.0"
[[params.versions]]
version = "Legacy"
url = "/../legacy"
In the same example scenario as above, the config.toml file for the 7.0 branch (which is not the latest version in this case) would be:
On every commit Github Actions will build the version of the site that the commit is on to ensure that Hugo can convert the content into a static site. It will also build all the other versioned branches to check that they work.
On a nightly basis, Github Actions will check to see if there have been any commits on the master branch since the last publish.
If there have been it will proceed with full build and publish.
This schedule is controlled by
build_and_release.yml
on the master branch.
This automated build will look for any branches matching the pattern (legacy|[0-9]+\.[0-9]+) and for each one will do the following:
Once each site has been processed it will:
index.hml file that will redirect to the latest version sub-directory.Although the build is run on the master branch it will use the HEAD commit of each of the release branches to build the site(s).
The build and release can be forced by adding the text [publish] to the commit message on master.
This is useful in testing, or if updated documentation is needed for any reason.
When you make changes to one of the version branches (7.0, 7.1, etc.), either directly or with a pull request from a feature branch, you will need to merge the changes up through each of the versions until they reach master.
Merging up through multiple branches is tedious when done manually so you can use the merge_up.sh script in the root of this repo.
You can either run it without any arguments to merge from legacy all the way up to master with all branches in between.
Alternatively you can supply the name of the branch to start from, e.g. ./merge_up.sh 7.0, which will save it doing a pointless merge up from older branches that have not changed.
When you run it, it will tell you the merge path and get you to confirm.
If there are no merge conflicts then it will perform all the merges and return you to your current branch.
If there are conflicts at any stage then it will stop at that point.
You will then need to fix the conflicts and commit the merge.
You can then run merge_up.sh again to do the rest of the merges.
The nature of a change to the site/documentation will determine which git branch the change is made on.
Any changes that are specific to a Stroom version, e.g. documenting a new feature in that version should be made on the oldest branch that contains that feature.
If the change relates to an as yet unreleased version of Stroom then make the change on master.
Adding news items or release notes for new versions should be done on the latest release branch. The News/Releases section is not included in old versions when released.
Ideally changes to the look of the site, e.g. upgrading the Docsy theme sub-module to a new commit, adding shortcodes or tweaking the CSS should be done on all branches so when switching between branches the look doesn’t change.
This means this sort of change should be done on the oldest published version branch and then merged up the chain to the others, e.g. legacy => 7.0 => 7.1 => master.
In some cases a change to the look may require significant refactoring of the content, e.g. changes to a shortcode. In the event of this it may be necessary to only make the change on the latest release branch and for different versions to have a slightly different look. The decision on how best to tackle these situations will have to be on a case by case basis.
To make it easier to test how the combined site will look with multiple versions the following script can be run to mock up a multi-version site. It does the following:
/tmp/stroom-docs_mock_combined_site/.To run this script do:
create_mock_combined_site.sh
The combined site can be served using something like the Python simple HTTP server, e.g.
cd /tmp/stroom-docs_mock_combined_site
python -m SimpleHTTPServer 8888
Then open a browser at localhost:8888.
As each version of the site is a copy of the same thing the content will be all the same but it allows you to test the version drop down and archived banner.
Stroom’s documentation is created using the static site generator Hugo . This converts markdown content into a rich HTML site. The markdown content in stroom-docs is not intended to be read as-is in GitHub, it needs to be rendered first.
The full documentation for Hugo can be found here . The site also uses the Docsy theme for Hugo. The documentation for Docsy can be found here . The Docsy theme provides a lot of the styling but also adds other features and shortcodes. You should consult the Docsy documentation in the first instance.
To maintain a degree of consistency in the documentation you should use this section as a reference for how to layout your content.
The documentation makes heavy use of Hugo shortcodes for adding page elements such as links, icons, images, etc. Shortcodes make it easy to change how a page element is styled by just changing the shortcode.
Hugo includes many
shortcodes
, the Docsy theme adds some
more
and there are some bespoke stroom-docs ones in layouts/shortcodes/.
To make your life easier when editing the documentation it is highly recomended to use an editor that supports text snippets. Snippets make it very quick to add shortcodes into the documentation.
For example the following snippet adds a skeleton front matter to a page.
snippet hfront "Hugo markdown metadata front matter" b
---
title: "${1:Title}"
linkTitle: "$1"
#weight:
date: `date "+%Y-%m-%d"`
tags: $2
description: >
$3
---
$0
endsnippet
{
"hugo-front-matter": {
"prefix": "hfront",
"body": [
"---",
"title: \"${1:Title}\"",
"linkTitle: \"$1\"",
"#weight:",
"date: `date \"+%Y-%m-%d\"`",
"tags: $2",
"description: >",
" $3",
"---",
"",
"$0"
],
"description": "Hugo markdown metadata front matter"
}
}
Ideally files and directories should be named using lower-kebab-case, e.g. site-structure.md.
All page content, i.e. markdown, is located underneath content/en.
This directory has one sub-directory for each of the top nav bar items.
Each of the following sections can have a different styling that is appropriate to its content, e.g. documentation vs blog.
The landing page is located at content/en/_index.html.
This is the page that users will initially see, unless visiting via a direct link.
about)A single page describing what stroom is.
docs)This is where all the documentation for installing, administering and using stroom is located.
news)This is a blog type section that contains a page for each new Stroom release and a set of blog posts for Stroom news items.
The pages in the two sub-sections (news and releases) are displayed in chronalogical order based on the date key in the page’s front matter.
news/news)This sub section has a flat structure with one .md file per news item.
Each file should be named in the form YYYYMMDD-<name>.md.
The date key should be set in the front matter to match the date of the file.
Hugo will use this date key to order the files in the menu.
The date should be set in ISO 8601 date format, i.e.
date: 2021-07-09
news/releases)Each new minor version release of Stroom should have a file in this directory.
They should be named in the form vXX.YY.md where XX is the zero padded major version and YY is the zero padded minor version, e.g. v07.01.
The zero padding is to ensure correct ordering by default withouth having to resort to using weight in the front matter.
The front matter should be set along these lines:
---
title: "Version 7.0"
linkTitle: "7.0"
date: 2021-07-07
description: >
Key new features and changes present in v7.0 of Stroom and Stroom-Proxy.
---
community)This section provides information for people wanting to contribute to the development of Stroom and its peripheral repositories.
This can include developer documentation for building and developing Stroom.
This has the same structure as docs.
The docs and community top level sections have a tree structure for their content.
Each of these directories will contain three different types of entities:
_index.md)building.md)The following is an example of part of the structure of the community section.
├── documentation/ Documentation section directory
│ ├── building.md Page
│ ├── _index.md Documentation section index page
│ ├── style-guide/ Style guide section directory
│ │ ├── basic-elements.md Page
│ │ ├── icon-gallery.md Page
│ │ ├── _index.md Style guide section index page
│ │ ├── site-structure.md Page
│ │ └── using-images.md Page
│ └── versions.md Page
└── roadmap.md Page
A section can essentially contain branches (sections) and leaves (pages).
A branch (i.e. a section) is defined by a directory that contains an _index.md file.
The front matter in this index file defines the meta data for that section, e.g. the title, date, tags, description, etc.
A leaf (i.e. a page with no children) is just a markdown file with front matter.
The front matter for branches and leaves works in the same way.
If you already have a section that you want to add a new child page to then you will already have a structure like this:
└── my-section/
├── _index.md
├── a-page.md
└── another-page.md
To add a new page simple create a .md file for the new page in the section directory, e.g.
└── my-section/
├── _index.md
├── a-page.md
├── another-page.md
└── new-page.md
Add the front matter to the top of the new page file. e.g.
---
title: "My Long Wordy Title"
linkTitle: "My Short Title"
weight: 20
date: 2022-01-27
tags:
description: >
A new page describing stuff.
---
The new page should now appear in the list of child pages on the section page and in the left hand navigation pane.
If you want to control the position of the new page relative to its siblings then adjust the weight of this page and that of its siblings to get the order that you want.
If you want to add a sub-section to an existin section then you will already have a structure like this:
└── my-section/
├── _index.md
├── a-page.md
└── another-page.md
To add a new sub-section create a sub-directory within the existing directory (with a name that roughly matches the section name) and create an _index.md file within it, e.g.
└── my-section/
├── my-new-sub-section/
│ └── _index.md
├── _index.md
├── a-page.md
└── another-page.md
In the _index.md file add front matter to the top, e.g.
---
title: "My Long Wordy Section Title"
linkTitle: "My Short Section Title"
weight: 20
date: 2022-01-27
tags:
description: >
A new section for stuff.
---
As with pages, adjust the weight of the section and its siblings to get the order you require.
To add pages to this new section see Add a new child page above.
If you are not sure if you need to add a whole new sub-section or just a child page you can just add a new sub-section and add content to the _index.md file as if it were a simple page.
If you later realise that you need child pages then move the content out into a child page and create other sibling pages to it.
Front matter in Hugo is a set of meta data at the top of each page that controls which menus include the page as well as providing information about the page, e.g.
---
title: "Site Structure"
linkTitle: "Site Structure"
weight: 10
date: 2021-07-20
tags:
- style
- TODO
description: >
Describes the file and directory structure for the site.
---
Hugo supports front matter in YAML, JSON and TOML, however for consistency all front matter in stroom-docs should be in YAML format.
This is the section/page title and will become the h1 heading (in HTML/Markdown terms) on the section/page.
The linkTitle is the text that is displayed in the left hand navigation sidebar.
It should be the same as title unless the title is quite long, in which case a shorter version should be used so it fits in the sidebar.
The weight controls the position of the page/section within the other pages/sections of its parent.
i.e. it controls the order of the pages/sections in the left hand navigation bar and the list of child items on a section index.
If no weight is provided then Hugo will use date, then linkTitle, then the file path.
To assist with re-ordering pages you can use the script change_weights.sh in the root of the repo.
E.g. to change the order of the child items of the user-guide section do the following:
./change_weight.sh content/en/docs/user-guide
The date should be set/updated to the current date when a page/section is created or modified. This data is show at the bottom of the page and tells the reader when the page was last updated.
In the front matter, tags is a list of tags that are applicable to the document and allow documents to be searched for by tag.
Tag names should conform to the following conventions:
reference-data, even for abbreviations.TODO, which is always upper case.pipeline rather than pipelines.Avoid using too many unique tag names as it will make the list of tags in the sidebar to large to be useful. When setting a tag on a document consult the list of existing tags to ensure consistency and to see if a more applicable tag already exists.
Add the TODO tag to a page when the page is incomplete.
This makes it easy to find areas of the documentation that are in need of attention.
If you want to apply a tag to all descendant pages of a section you can add this to the front matter of the section:
cascade:
tags:
- install
This will then apply all of tags added to tags to each descendant page.
A short description of what the page/section covers. This will be shown on the index page of its parent.
Each sentence must start on a new line, even in numbered/bulleted lists. This makes it easier to move sentences around or to remove them and limits the scope of changes when it comes to git diffs and merges. When the markdown is rendered into HTML/PDF, the sentences will be joined into a single paragraph.
See this site for more of the reasons behind sentence per line. Though this link relates to Asciidoc, the same logic applies to markdown.
For example:
This is the first sentence of the paragraph.
This is the second.
This it the third and final one.
This is the start of a new paragraph.
Which renders as:
This is the first sentence of the paragraph. This is the second. This it the third and final one.
This is the start of a new paragraph.
This is the first sentence of the paragraph. This is the second. This it the third and final one.
This is the start of a new paragraph.
Which renders as:
This is the first sentence of the paragraph. This is the second. This it the third and final one.
This is the start of a new paragraph.
Long lines should not be hard wrapped by adding line breaks. You should instead rely on your editor to soft wrap long lines that cannot fit on the visible screen area. The process of hard wrapping long lines will vary from editor to editor and not all editors support re-wrapping lines after the content has changed. It also relies on each person’s editor being configured to the same wrap column. Adding hard wraps also means a slight change at the start of a paragraph will potentially cause all subsequent lines to be re-wrapped and thus appear as a substantial difference in the commit.
## Don't do this
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
## Do this instead
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
In some circumstances, e.g. a list of items that is not bulleted, you may want to prevent the joining of adjacent lines when rendered.
You can force a line break by adding two spaces ␣␣ at the end of a line.
Paragraph 1.
One␣␣
Two␣␣
Three
Paragraph 2.
Which renders as:
Paragraph 1.
One
Two
Three
Paragraph 2.
Paragraph 1.
One
Two
Three
Paragraph 2.
Which renders as:
Paragraph 1.
One Two Three
Paragraph 2.
e.g:
The text belonging to the previous heading.
## A Heading
## A sub heading
The text of this heading.
A second sentence in this paragraph.
A new paragraph.
A second sentence in this paragraph.
Here are some bullets:
* Bullet Z.
* Bullet A.
This is an additional sentence for this bullet point.
And so is this.
* Sub-bullet AX.
This is an additional sentence for this bullet point.
And so is this.
* Bullet F.
Here are some numbered steps:
1. Step 1.
1. Step 2.
1. Step 3.
Another random line.
## Another Heading
The page title uses heading level one (# in markdown) so all markdown headings should be >= 2 (## , ### , #### , etc.).
Headings should have two blank lines above them for clarity in the raw markdown.
The # characters should always be followed by one space character
The following is an example of the heading levels.
# Heading level 1
DON'T use this level in your documents.
Level one headings will be generated from the `title` in the document's front matter.
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6
Markdown supports an alternate style for headings, as shown below. Don’t use this style as it is not clear from the symbols what the heading level is.
Heading level 1
===============
Don't use this style.
Heading level 2
---------------
Don't use this style.
The page table of contents (right hand pane) is controlled by this in config.toml.
[markup]
[markup.tableOfContents]
endLevel = 4
ordered = false
startLevel = 2
The maximum depth of the table of contents can be controlled with endLevel.
This is an example of a level 2 heading.
This is an example of a level 3 heading.
This is an example of a level 4 heading.
This is an example of a level 5 heading.
This is an example of a level 6 heading.
A simple paragraph block quote.
> This is a simple block quote.
> This is the second sentence on the same line.
This is a simple block quote. This is the second sentence on the same line.
A pair of spaces at the end of a line can be used to force line breaks, e.g.:
> This is a multi line block quote.␣␣
> This is the second line.␣␣
> This is the third line.
This is a multi line block quote.
This is the second line.
This is the third line.
* Fruit.
Make sure you get your five-a-day.
* Meat
* Beef
* Chicken
* Vegetables.
Numbered list items should all be numbered with number 1 so that the markdown render handles the consecutive numbering.
This makes the file easier to edit and means the addition of one item in the middle does not cause a change to all the lines after it, e.g:
1. Item one.
This is some extra content for step 1.
1. Item two.
1. Sub-item A.
1. Sub-item B.
1. Item three.
* [ ] Item 1.
This is some extra content for item 1.
* [ ] Item 2.
* [x] Item 2a.
* [ ] Item 2b.
* [x] Item 3.
Name
: Godzilla
Birthplace
: Japan
Color
: Green
Tables should ideally have its columns aligned in the markdown for clarity in the raw markdown.
## Ideally do this
| Artist | Album | Year |
|-----------------|----------------|------|
| Michael Jackson | Thriller | 1982 |
| Prince | Purple Rain | 1984 |
| Beastie Boys | License to Ill | 1986 |
## But this is acceptable
| Artist | Album | Year |
|-|-|-|
| Michael Jackson | Thriller | 1982 |
| Prince | Purple Rain | 1984 |
| Beastie Boys | License to Ill | 1986 |
Both will produce the same result. The latter can be harder to read in markdown form. The former is harder to create and update in markdown form.
| Artist | Album | Year |
|---|---|---|
| Michael Jackson | Thriller | 1982 |
| Prince | Purple Rain | 1984 |
| Beastie Boys | License to Ill | 1986 |
As the Markdown content is procesed by Hugo and is not intended to be read in its raw Markdown form it means it is possible to include comments in the content. This can be useful when you want to leave development comments in the content that are not for display in the rendered site. Comments are done with the HTML comment syntax, i.e.
<!-- This is a comment -->
<!--
This is a
mult-line comment
-->
While links can be added using standard markdown link syntax you should use Hugo shortcodes to add them. The advantage of the shortcode is that Hugo will check for broken links when building the site.
As this site is deployed to environments with no internet connect and is also released in PDF form it is important that any links to locations outside of the this site (i.e. on the internet) are clearly marked. To include an external link do the following:
This is a link to Stroom on Github with a title.
This is a link to {{< external-link "Stroom on Github" "https://github.com/gchq/stroom" >}} with a title.
This is the same link with no title, https://github.com/gchq/stroom .
This is the same link with no title, {{< external-link "https://github.com/gchq/stroom" >}}.
Some external links are to other Stroom URLs are versioned.
If you need to link to a site external to this one that has the Stroom version in the URL then you can use the tag @@VERSION@@ in the URL.
This will be translated into the Stroom version of this site, as seen in the Stroom Version (…) drop down at the top of the page.
This saves you from having to update the URL on each release of Stroom.
This is a versioned URL https://gchq.github.io/stroom/v7.0
This is a versioned URL {{< external-link "https://gchq.github.io/stroom/v@@VERSION@@" >}}
legacy as that is not an actual Stroom version.
You can link to headings on a page using its anchor. The anchor for a heading is the heading text with:
-- characters, e.g. --- are replaced with a single -For example the heading Mr O'Neil's 1st Event (something) becomes as an anchor #mr-oneils-1st-event-something.
See The link examples below that use anchors.
If you have two headings on the same page then Hugo will suffix the anchors with a sequential number to ensure uniqueness of the anchor. For example, with the following markdown:
## Apples
### Example
## Oranges
### Example
Hugo will create the following anchors:
apples
example
oranges
example-1
If you want to avoid confusion and removed the risk of anchors breaking if new headings are added in the middle, then you can explicitly name anchors:
## Apples
### Example {#apples-example}
## Oranges
### Example {#oranges-example}
This is only worth doing if you want to link to these heading.
Shortcode links are slightly more verbose to type but are preferable to markdown style links as the link target will be checked at site build time so you know all the links are correct.
Hugo has ref and relref link shortcodes.
Use only relref as this will be translated into a relative path when the site it built ensuring that the site can be run from any base path.
The following are some example of different links to internal content.
A link to a heading anchor on this page.
[link]({{< relref "#alerts" >}})
A link to a heading anchor on another page, using an absolute path.
[link]({{< relref "community/documentation/style-guide/using-images#captions" >}})
A link to a heading anchor on page above this one, using a relative path.
[link]({{< relref "../versions" >}})
A link to a heading anchor on another page, using only the unique page name. This is quicker to type and won’t break if pages are moved but will not work if the page name is not unique.
[link]({{< relref "running#basic-configuration" >}})
A link to a branch/section in the document tree, i.e. to the \_index.md.
[link]({{< relref "docs/HOWTOs" >}})
A link to the next page in the current section. If the current page is the last page in the section then no link will be displayed. What the next page is is defined by the page weights or the default ordering of pages in the section.
This is useful when you have a set of pages in a section that have a natural flow, e.g. where the pages in a section are the sequential steps in an installation guide.
The link looks like this(with the page title in the link text and the hover tip showing both the page title and the description):
Next page - Images{{< next-page >}}
A link to the previous page in the current section. If the current page is the last page in the section then no link will be displayed. What the previous page is is defined by the page weights or the default ordering of pages in the section.
This is useful when you have a set of pages in a section that have a natural flow, e.g. where the pages in a section are the sequential steps in an installation guide.
The link looks like this(with the page title in the link text and the hover tip showing both the page title and the description):
Previous page - Markdown Style Conventions{{< prev-page >}}
Markdown style links should not contain the .md extension as this will be stripped when the site is generated, e.g. for the following content:
/content
/en
/docs
/section-x
/sub-section-a
_index.md
page1.md
page2.md
/sub-section-b
_index.md
page1.md
page2.md
This will become:
/docs
/section-x
/sub-section-a
/page1
/page2
/sub-section-b
/page1
/page2
in the rendered site.
A link to a heading anchor on this page.
[link](#alerts)
A link to a heading anchor on another page, using a relative link.
[link](../using-images#captions)
A link to a heading anchor on another page, using an absolute link.
[link](/docs/style-guide/using-images#captions)
You can create a link to download a file, like these:
Download a file .
Download mock_stroom_data.csv
{{< file-link "quick-start-guide/mock_stroom_data.csv" >}}Link Title{{< /file-link >}}
{{< file-link "quick-start-guide/mock_stroom_data.csv" />}}
All paths are relative to /assets/files/.
If you need to create a link to an item in the Glossary you can use the glossary shortcode.
E.g.
A feed is something you should know about, and so are streams .
A {{< glossary "feed" >}} is something you should know about, and so are {{< glossary "stream" "streams" >}}.
The argument to the shortcode is the glossary term. This should match the heading text on the Glossary page exactly, ignoring case. It will be converted to an HTML anchor so that you can link directly to the heading for the term in question.
Inline code looks like this.
Inline code `looks like this`.
Code blocks should be surrounded with fences ```language-type and ``` with the language type always specified to ensure correct syntax highlighting.
If the language type is not supplied then styling will be different to fenced blocks with a language.
This is a markdown example of a fenced code block containing XML content.
<root>
<child attr="xxx">some val</child>
</root>
```xml
<root>
<child attr="xxx">some val</child>
</root>
```
text.
The following are some example of rendered code blocks:
id,date,time
1,6/2/2018,10:18
2,12/6/2017,5:58
3,6/7/2018,11:58
---
root:
someKey: "value"
<root>
<child attr="xxx">
some val
</child>
</root>
echo "${VAR}"
If you need to show line numbers or to highlight sections of a code block then you can use the code-block shortcode.
This shortcode takes the following named arguments:
text.true|false).
Defaults to true.2-8,13,25-30.
Defaults to no line highlighting.The following is an example of how to use the shortcode.
{{< code-block language="xml" highlight="2-5,8" >}}
<root>
<child attr="xxx">
some val
</child>
<child attr="xxx">
some val
</child>
<child attr="xxx">
some val
</child>
</root>
{{< /code-block >}}
Default behaviour
{{< code-block >}}
...
{{< /code-block >}}
With line numbers, a language and a starting line number
{{< code-block language="xml" start="5" >}}
...
{{< /code-block >}}
With line numbers, a language and highlighted lines
{{< code-block language="xml" highlight="2-5,8" >}}
...
{{< /code-block >}}
With a language and highlighted lines, but without line numbers
{{< code-block language="xml" lines="false" highlight="2-5,8" >}}
...
{{< /code-block >}}
To demonstrate commands being run on the command line you can use the command-line shortcode.
This results in a code block with the shell prompt displayed on the left of each line.
It also means the prompt part is not selectable when the user selects the text for copy/pasting.
The shortcode takes the following positional arguments:
user.localhost.bash.If you want to display shell output then prefix each output line with (out).
It will then be displayed without a prompt.
To display a blank line with no prompt then have a line with just (out) in it.
If your shell command is very long then you can split it into multiple lines using the shell line continuation character \ which must be the last character on the line.
If this character is present then it will be rendered with a different prompt to indicate it is a continuation.
Readers can then copy/past the muli-line command into a shell and run it.
{{< command-line "david" "wopr" >}}
echo hello \
world
(out)hello world
id
(out)uid=1000(david) gid=1000(david)
{{< command-line >}}
To demonstrate commands being run in a MySQL shell you can use the sql-shell shortcode.
This works in a similar way to the command-line shortcode but has a different prompt and no shortcode arguments.
If you want to display shell output then prefix each output line with (out).
It will then be displayed without a prompt.
If your sql statement is multi-line, prefix all lines except the first with (con) (for continuation).
Continuation lines will be rendered with a continuation prompt (->).
To display a blank line with no prompt then have a line with just (out) in it.
{{< sql-shell >}}
select *
(con)from token_type
(con)limit 2;
(con)+----+------+
(con)| id | type |
(con)+----+------+
(con)| 1 | user |
(con)| 2 | api |
(con)+----+------+
(out)2 rows in set (0.00 sec)
(out)
select database();
(out)+------------+
(out)| database() |
(out)+------------+
(out)| stroom |
(out)+------------+
(out)1 row in set (0.00 sec)
{{< sql-shell >}}
Some code or text examples may be too large for a fenced block so you can put the content in a separate file and include it in-line like so.
<?xml version="1.1" encoding="UTF-8"?>
<dataSplitter
xmlns="data-splitter:3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="data-splitter:3 file://data-splitter-v3.0.1.xsd"
version="3.0">
<!--
GEOHOST REFERENCE FEED:
CHANGE HISTORY
v1.0.0 - 2020-02-09 John Doe
This is a reference feed for device Logical and Geographic data.
The feed provides for each device
* the device FQDN
* the device IP Address
* the device Country location (using ISO 3166-1 alpha-3 codes)
* the device Site location
* the device Building location
* the device Room location
*the device TimeZone location (both standard then daylight timezone offsets from UTC)
The data is a TAB delimited file with the first line providing headings.
Example data:
FQDN IPAddress Country Site Building Room TimeZones
stroomnode00.strmdev00.org 192.168.2.245 GBR Bristol-S00 GZero R00 +00:00/+01:00
stroomnode01.strmdev01.org 192.168.3.117 AUS Sydney-S04 R6 5-134 +10:00/+11:00
host01.company4.org 192.168.4.220 USA LosAngeles-S19 ILM C5-54-2 -08:00/-07:00
-->
<!-- Match the heading line - split on newline and match a maximum of one line -->
<split delimiter="\n" maxMatch="1">
<!-- Store each heading and note we split fields on the TAB (	) character -->
<group>
<split delimiter="	">
<var id="heading"/>
</split>
</group>
</split>
!-- Match all other data lines - splitting on newline -->
<split delimiter="\n">
<group>
<!-- Store each field using the column heading number for each column ($heading$1) and note we split fields on the TAB (	) character -->
<split delimiter="	">
<data name="$heading$1" value="$1"/>
</split>
</group>
</split>
</dataSplitter>
The card has a maximum height and will show scrollbars as required.
Examples of how to use in-line files are:
{{< textfile "style-guide/in_line_file_example.xml" "xml" >}}My caption{{< /textfile >}}
{{< textfile "style-guide/in_line_file_example.xml" >}}My caption{{< /textfile >}}
{{< textfile "style-guide/in_line_file_example.xml" />}}
This site uses
Prismjs
for syntax highlighing code blocks.
PrismJs supports a large number of different languages however only certain languages have been included with this site.
The language specified in the markdown code fence or in the command-line shortcode must be in the list of included languages.
The list of included language names are:
sh
bash
css
csv
groovy
http
java
javascript
jq
json
python
regex
scss
sql
text
toml
xml
yaml
To include extra languages in this site you need to build a new version of the prism.js and prism.css files.
This can be done
here
.
When creating new versions of these file you must include the languages and plugins already included else you may break this site.
The generated files are then copied over the top of /static/css/prism.css and /static/js/prism.js.
Both files include a comment at the top with the link to the PrismJs download page with the currently included items selected.
Use this link then add any additional items, bearing in mind the size of the download and its impact on page load times.
An example of the download link is https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+csv+groovy+java+jq+json+markdown+python+regex+scss+sql+toml+yaml&plugins=line-highlight+line-numbers+command-line+toolbar+copy-to-clipboard+treeview */
The markdown for this is:
{{% warning %}}
This is a warning that can contain _markdown_.
{{% /warning %}}
This is a warning that can contain markdown.
The markdown for this is:
{{% page-warning %}}
This is a warning that can contain _markdown_.
{{% /page-warning %}}
The markdown for this is:
{{% note %}}
This is a note that can contain **markdown**.
{{% /note %}}
Useful for linking to other areas of the documentation or to external sites.
The markdown for this is:
{{% see-also %}}
[Note block quote]({{< relref "#note-block-quote" >}})
[Warning block quote]({{< relref "#warning-block-quote" >}})
{{% /see-also %}}
This is some info that can contain markdown.
The markdown for this is:
{{% pageinfo %}}
This is some info that can contain **markdown**.
{{% /pageinfo %}}
Used to indicate areas of the documentation that are unfinished or incorrect.
markdown.
The markdown for this is:
{{% todo %}}
This is a TODO that can contain `markdown`.
{{% /todo %}}
Cards can be used to display related content side by side. Each card can contain markdown and/or Hugo short codes. The cards will be displayed horizontally to fill the width of the page.
---
root:
someKey: "value"
<root>
<child attr="xxx">some val</child>
</root>
The markdown for this is:
{{< cardpane >}}
{{< card header="YAML" >}}
```yaml
---
root:
someKey: "value"
```
{{< /card >}}
{{< card header="XML" >}}
```xml
<root>
<child attr="xxx">some val</child>
</root>
```
{{< /card >}}
{{< /cardpane >}}
Hugo/Docsy have shortcodes for tabbed panes however these mean only one tab will be printed or visible in the generated PDF so their use should be avoided.
All Images should be placed in /assets/images/ or within a descendent directory of it.
Images should be added to the markdown using the image shortcode.
This ensures a consistent look for all images and allows control of the size of the image.
The short code can be added in the following ways.
{{< image "style-guide/stroom-oo.svg" "200x" >}}
{{< image "style-guide/stroom-oo.png" >}}
{{< image "style-guide/stroom-oo.svg" "200x" >}}Image caption{{< /image >}}
All paths used in the image shortcode are relative to /assets/images.
The following shows an example of the directory structure.
/assets
/images
/section-x
/sub-section-y
/page1
/image.svg
/content
/en
/docs
/section-x
/sub-section-y
page1.md - #image shortcode used in here
Where images are only used by one page then the directory structure in /assets ought to mirror that of the page the images are used in, as shown above.
If images are used by multiple pages then some other sensible organisation of the images should be used, e.g. /assets/images/section-x if they are limited to pages in one section, or /aaets/images/common if they are used in multiple sections.
The image can be displayed with a caption:
The image can be defined with a maximum width (e.g. "300x") or a maximum height ("x200").
.png files can be rendered in their original size by omitting the size argument.
Or they can be rendered with a set size.
/assets/ resourcesFor images that are shared by multiple page bundles, e.g. stroom icons, place them in /assets/images/.
The image path is relative to /assets/images/, e.g. file /assets/images/style-guide/svg-example.svg becomes:
{{< image "style-guide/svg-example.svg" "200x" >}}
PlantUML is the favoured tool for producing diagrams such as UML diagrams, entity relationship diagrams and other more general architecture diagrams. The diagrams are written in plain text which makes them easy to version control. The plantUML syntax can then be converted into image files, e.g. .svg files.
A plantUML diagram looks like this in plain text form:
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
PlantUML diagrams should be saved in a dedicated .puml file in the same folder as the page that will display it.
If it is needed by multiple pages then it should be saved in /assets/images/.
The build process will convert all .puml files to a corresponding .puml.svg file.
These generated .puml.svg files are ignored by git so need to be regenerated at build time or when you change a .puml file.
The images can be generated by doing:
./container_build/runInPumlDocker.sh SVG
You should embed an PlantUML image like this, using the .puml.svg file (that may not yet exist, but will have to exist before the site is built):
Images can be located in a
page bundle
.
This is where the page is defined as a named directory (rather than a .md file) with an associated index.md file for the markdown contnet.
All other items in the directory are page resources that can be used by the page, i.e. image files.
index.md.
Use the image short code to display an image file that is located in the same directory as the page.
For the short code to work the page must be a leaf bundle (index.md) or a branch bundle (_index.md), i.e:
/docs
/MyPage
index.md - #image shortcode used in here
example.svg
or
/docs
/MySection
/Page1
index.md
/Page2
index.md
_index.md - #image shortcode used in here
example.svg
In the above example, the shortcode would look like:
{{< image "example.svg" "200x" >}}
Sometimes it is useful to display an image of certain user interface elements to explain something. Rather than use screenshots which are very difficult to keep up to date, you can instead use some simple shortcodes to display some UI elements, e.g. buttons, pipeline elements, etc. By using shortcodes, any change to the look of the Stroom UI means only the shortcode content and their styling need to change, without having to recreate tens or hundreds of screenshots.
Stroom UI icons such as
or
can be added in line using the shortcode stroom-icon.
Arguments:
icon_file_path - The filename (and path) of the icon file.
The path is relative to /assets/images/stroom-ui/.title (optional) - The hover tip title that will be given to the icon.state (optional) [enabled|disabled] - Whether the button is enabled or disabled.
Defaults to enabled.The full list of available icons can be found in the Icon Gallery.
document icons are in upper sentence case.
Also note the extension of the icon files as most are .svg but some are .png.
E.g:
Simple use:
Custom name:
Disabled document icon:
Simple use: {{< stroom-icon "save.svg" >}}
Custom name: {{< stroom-icon "key.svg" "Lock" >}}
Disabled document icon: {{< stroom-icon "document/Feed.svg" "Feed" "disabled" >}}
To display a UI button you can use the shortcode stroom-btn with the button title as its only argument.
Arguments:
title - The text to display on the button.
and
{{< stroom-btn "Ok" >}}
and
{{< stroom-btn "Cancel" >}}
To display a pipeline element (as seen on the Structure sub-tab on the Pipeline screen), like
splitFilter
, you can use the shortcode pipe-elm.
Arguments:
element_name - The name of the pipeline element (case insensitive), e.g. XsltFilter.display_name (optional) - The display name for the pipeline element.
If a display name is not provided then the lower camel case form of the element name will be used as the display name.The icon will be selected to match the element name provided.
This is an xsltFilter with its default name:
xsltFilter
This is a splitFilter with a custom name:
My Split Filter
This is an xsltFilter with its default name:
{{< pipe-elm "xsltFilter" >}}
This is a splitFilter with a custom name:
{{< pipe-elm "splitFilter" "My Split Filter" >}}
To display a top level Stroom document tab, like
Big Index
×
, you can use the shortcode stroom-tab.
Arguments:
icon_filename - The filename of the icon to use (relative to assets/images/stroom-ui/document/) (case sensitive), e.g. Pipeline.svg.title - The text to display in the tab, e.g. Indexing Pipeline.state (optional) - Whether the tab is active or not (active or inactive). Defaults to inactive.For a full list of all available icons see the Icon Gallery
Simple:
MY_FEED
×
Custom name:
My Translation
×
Active:
My Translation
×
Unsaved:
* My Translation
×
Simple: {{< stroom-tab "Feed.svg" "MY_FEED" >}}
Custom name: {{< stroom-tab "XSLT.svg" "My Translation" >}}
Active: {{< stroom-tab "XSLT.svg" "My Translation" "active" >}}
Unsaved: {{< stroom-tab "XSLT.svg" "My Translation" "active" "unsaved" >}}
To display a selected menu item you can use the stroom-menu shortcode.
For example to demonstrate creating a folder using the context menu:
The markdown for this example is:
{{< stroom-menu "New" "Folder" >}}
The shortcode takes one argument per menu item. The list of available menu items with an icon are in this gallery. Menu item names are case-sensitive. If the menu item name is not in the gallery then it will be displayed without an icon, e.g.:
This shortcode can be used in-line like
this.
This page can be used as a reference for finding icons and their filenames to use them in the documentation.
See here for how to add icons to pages.
General icons used in Stroom.
Example:
{{< stroom-icon "edit.svg" >}}
add-above.svg
add-below.svg
add.svg
alert.svg
clear.svg
close-grey.svg
close.svg
collapse-up.svg
copy.svg
database.svg
delete.svg
deleted.svg
dependencies.svg
disable.svg
down.svg
download.svg
drop-down.svg
edit.svg
ellipses-horizontal.svg
ellipses-vertical.svg
error.svg
expand-down.svg
explorer.svg
fast-backward-green.svg
fast-backward.svg
fast-forward-green.svg
fast-forward.svg
fatal.svg
favourites.svg
feed.svg
field.svg
file-formatted.svg
file-raw.svg
file.svg
filter.svg
folder-tree.svg
folder.svg
format.svg
function.svg
generate.svg
help.svg
hide.svg
history.svg
info-deleted.svg
info-warning.svg
info.svg
jobs.svg
key.svg
lock-green.svg
locked-amber.svg
logo.svg
logout.svg
monitoring.svg
move.svg
nodes.svg
oo.svg
operator.svg
password.svg
pause.svg
play-green.svg
play.svg
process.svg
properties.svg
raw.svg
refresh-green.svg
refresh.svg
remove.svg
ruleset.svg
save.svg
saveas.svg
settings-blue.svg
settings-grey.svg
settings.svg
shard-close.svg
shard-flush.svg
show.svg
spinner.svg
step-backward-green.svg
step-backward.svg
step-forward-green.svg
step-forward.svg
step.svg
stepping.svg
stop-red.svg
stop.svg
table-nested.svg
table.svg
tree-closed.svg
tree-leaf.svg
tree-open.svg
undo.svg
unlock-amber.svg
unlocked-green.svg
up.svg
upload.svg
user-disabled.svg
user.svg
users-disabled.svg
users.svg
volumes.svg
Icons used for the different pipeline elements.
Base path: pipeline
Example:
{{< stroom-icon "pipeline/stream.svg" >}}
ElasticSearch.svg
StroomStatsStore.svg
analyticOutput.svg
apache_kafka-icon.svg
file.svg
files.svg
hadoop-elephant-logo.svg
id.svg
index.svg
json.svg
kafka.svg
recordCount.svg
recordOutput.svg
referenceData.svg
search.svg
solr.svg
split.svg
statistics.svg
stream.svg
stroomStats.svg
text.svg
xml.svg
xmlSearch.svg
xsd.svg
xslt.svg
Icons used for the different document entity types, i.e. those seen in the explorer tree.
Base path: document
Example:
{{< stroom-icon "document/Index.svg" >}}
AnalyticOutputStore.svg
AnnotationsIndex.svg
Dashboard.svg
Dictionary.svg
ElasticIndex.svg
Feed.svg
Folder.svg
Index.svg
KafkaConfig.svg
Pipeline.svg
ReceiveDataRuleSet.svg
Script.svg
SelectAllOrNone.svg
SolrIndex.svg
StatisticStore.svg
StroomStatsStore.svg
System.svg
TextConverter.svg
Visualisation.svg
XMLSchema.svg
XSLT.svg
searchable.svg
Icons used on the Dashboard
Base path: dashboard.
expression.png
filter.png
format.png
group.png
sortaz.png
sortoff.png
sortza.png
Assorted images used in the user interface.
Base path: assorted
Example:
{{< stroom-icon "assorted/popup.png" "Menu selection" >}}
popup.png
Menu items with icons that are available for use with the stroom-menu shortcode.
This gallery of icons can be updated by running the following script which will copy all the icons from the stroom repository. You should ensure your local stroom repository is up to date and on the correct branch before running this.
e.g.
To update the available menu items edit the shortcode file layouts/shortcodes/stroom-menu.html and modify the icon_map variable..