Introduction
We write all of the nf-core documentation, including pipelines, in Markdown. Markdown is a simple markup language that allows you to write text in a way that is easy to read and write, but can be converted to HTML for display on the web.
In general, we follow the GitHub Flavored Markdown specification, but there are a few extra features that we support on nf-co.re.
Admonitions
Admonitions are used to highlight text in a box with a title. They are used to draw attention to important information, or to warn of potential problems.
You can use the following admonitions on this website:
Notes
:::note
He had half a mind just to keep on `falling`.
:::He had half a mind just to keep on falling.
Info
:::info
His face froze for a second or two and then began to do that terribly slow crashing `trick` that Arctic ice floes do so spectacularly in the spring.
:::His face froze for a second or two and then began to do that terribly slow crashing trick that Arctic ice floes do so spectacularly in the spring.
Tip
:::tip
The ships hung in the sky in much the same way that bricks don't.
:::The ships hung in the sky in much the same way that bricks don’t.
Warnings
:::warning
He smiled the smile that Zaphod had wanted to hit and this time `Zaphod` hit it.
:::He smiled the smile that Zaphod had wanted to hit and this time Zaphod hit it.
Danger
:::danger
One of the troublesome circumstances was the Plural nature of this Galactic Sector, where the possible `continually` interfered with the probable.
:::One of the troublesome circumstances was the Plural nature of this Galactic Sector, where the possible continually interfered with the probable.
Custom title
You can replace the default title with a custom one by adding a title attribute to the admonition, e.g.:
:::note{title="Don't Panic"}
Arthur Dent was grappling with his consciousness the way one grapples with a lost bar of soap in the bath. He lay, panting heavily in the wet air, and tried feeling bits of himself to see where he might be hurt. Wherever he touched himself, he encountered a pain. After a short while he worked out that this was because it was his hand that was hurting. Arthur nodded intelligently. Today was one of those bad days.
:::Arthur Dent was grappling with his consciousness the way one grapples with a lost bar of soap in the bath. He lay, panting heavily in the wet air, and tried feeling bits of himself to see where he might be hurt. Wherever he touched himself, he encountered a pain. After a short while he worked out that this was because it was his hand that was hurting. Arthur nodded intelligently. Today was one of those bad days.
Custom icon
You can replace the default icon with a custom one by adding a fontawesome icon class name with a leading period to the admonition, e.g.:
:::note{.fa-whale}
Another thing that got forgotten was the fact that against all probability a sperm whale had suddenly been called into existence several miles above the surface of an alien planet.
:::Another thing that got forgotten was the fact that against all probability a sperm whale had suddenly been called into existence several miles above the surface of an alien planet.
Custom icon and title
When changing both title and icon, the order is important. You need to first specify the icon and then the title, e.g.:
:::warning{.fa-flower-daffodil title="I wonder if it will be friends with me?"}
Curiously enough, the only thing that went through the mind of the bowl of petunias as it fell was Oh no, not again.
:::Curiously enough, the only thing that went through the mind of the bowl of petunias as it fell was Oh no, not again.
Collapsing admonitions
:::note{collapse}
Many people have speculated that if we knew exactly why the bowl of petunias had thought that we would know a lot more about the nature of the Universe than we do now.
:::Many people have speculated that if we knew exactly why the bowl of petunias had thought that we would know a lot more about the nature of the Universe than we do now.
GitHub style admonitions
For README.md files, you can also use the GitHub style admonitions/alerts.
This only works with markdown files fetched from pipeline repositories, so don’t use it in markdown files in the website repo.
> [!NOTE]
> Useful information that users should know, even when skimming content.This renders in the same way as regular admonitions on the nf-core website, but has the bonus of also rendering nicely when viewing the rendered markdown on github.com:
Code blocks
We use rehype-pretty-code to generate code blocks on the website. This allows us to add line numbers, highlight lines, add file names to code blocks, etc. These directives can be mixed and matched.
See the rehype-pretty-code documentation for more information.
Line numbers
```bash showLineNumbers
echo "Look ma!"
echo "Code line numbers!"
```echo "Look ma!"
echo "Code line numbers!"Highlight lines
```bash {1-3,5}
# This line is highlighted
echo "Me too"
echo "Third line lucky!"
# This line is not highlighted
# This is again!
# ok, nothing to see from here on..
```# This line is highlighted
echo "Me too"
echo "Third line lucky!"
# This line is not highlighted
# This is again!
# ok, nothing to see from here on..File names
You can add a file name to a code block by adding a title attribute to the code block, e.g.:
```groovy title="nextflow.config"
params {
input = null
}
```params {
input = null
}The icon next to the title is based on the file extension.
Code block captions
```groovy caption="Caption me this!"
// My awesome workflow
```// My awesome workflowPutting it all together
```groovy showLineNumbers {1, 5-7} title="main.nf" caption="This one is really special"
// My awesome workflow
process {
script:
"""
echo "This is awesome!"
"""
}
```// My awesome workflow
process {
script:
"""
echo "This is awesome!"
"""
}Mermaid diagrams
Mermaid is a simple markdown-like script language for generating charts from text via javascript. It supports many different types of diagrams, including flowcharts, sequence diagrams, gantt charts and class diagrams. To display them correctly on an nf-co.re page, you need to wrap them in a code block with the language set to mermaid,e.g.,:
```mermaid
%% https://xkcd.com/1195/
graph TD
start[Start] --> trap{Hey, wait, <br/> this flowchart <br/> is a trap!}
trap -- yes --> trap
```turns into:
Loading graph
LaTeX formulas
We support latex based formulas using KaTeX. To display them correctly on an nf-co.re page, you need to wrap them in a block surrounded by $$, e.g.:
$$
z_{n+1} = z_n^2 + c
$$turns into:
You can also display formulas inline by wrapping them in $ instead of $$, e.g.:
The lift $L$ is calculated as follows: $L = \frac{1}{2} \rho v^2 S C_L$gets rendered as:
The lift is calculated as follows: .