Chapter 13. Markdown
ReportServer provides robust support for rendering Markdown files (https://www.markdownguide.org/). This allows users to create and preview Markdown documents within the platform.
Following is an overview of the capabilities, along with examples demonstrating various Markdown syntax elements. A comprehensive documentation on Markdown syntax can be found here: https://www.markdownguide.org/ and https://www.markdownguide.org/basic-syntax/.
In ReportServer, it is important to set the content type of the Markdown file (e.g. markdown.md) to ''text/markdown''. This is necessary in order for ReportServer to recognize the file as Markdown files and being able to convert the files to HTML.
Features:
| Preview Markdown Tab | Available in the file system administration window, this tab allows users to preview the Markdown content directly within ReportServer. |
| Preview Markdown Button | Available in the Properties tab of the file system administration window, This button renders the Markdown and exports it as HTML into a new window. |
Markdown supports headers, which are created using the # symbol. The number of # symbols indicates the level of the header.
# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header
Task lists are rendered in Markdown as checkboxes, either selected or unselected.
A task can be represented as a list item where the first non-whitespace character is a left bracket [, followed by a space or an x (either lowercase or uppercase), then a right bracket ] followed by at least one space before any other content. An example is shown below.
Note that you have to include the - for creating an unordered task list as explained in Section 13.1.3., or numbers followed by a period for creating an ordered task list.
- [ ] task #1
- [x] task #2
1. [x] task #1
2. [ ] task #2
Comments can be added as shown in the following example:
: # (platform independent comment)To ensure maximum portability, it is essential to insert a blank line before and after this type of comment. This is because some Markdown parsers may not function correctly if definitions are directly adjacent to regular text.
Links can be created using square brackets [] for the text and parentheses () for the URL.
(https://www.reportserver.net)
Images are similar to links but prefixed with an exclamation mark !.
where http://localhost:8090/ReportServer/reportserver/fileServerAccess?id=9399 is the image's URL in ReportServer.
You can also set the height and width of the image as shown below. Both attributes are optional, so you can specify only the width or the height as well.
{width=100 height=200}
Inline code can be created using backticks, while code blocks are created using triple backticks.
Please ensure that there is a new line after the opening characters and before the closing characters when using code blocks.
Additionally, note that the enclosing characters for DOT code blocks (Section 13.1.10.) are not identical to those used in code blocks, although they may appear similar.
Here is some `inline code`.
```
Here is a code block.
It can span multiple lines.
```
ReportServer's Markdown syntax allows you to directly include Graphviz DOT files (https://graphviz.org/) into Markdown by as shown in the example below by enclosing them in ´´´. The DOT files are then rendered to SVG. You can find more information on Graphviz DOT on Section 14. You can find many more examples here: https://graphviz.org/gallery/.
Please ensure that there is a new line after the opening characters and before the closing characters when using DOT code blocks.
Additionally, note that the enclosing characters for code blocks (Section 13.1.9.) are not identical to those used in DOT code blocks, although they may appear similar.
´´´
// https://graphviz.org/Gallery/directed/cluster.html
digraph G {
fontname="Helvetica,Arial,sans-serif"
node [fontname="Helvetica,Arial,sans-serif"]
edge [fontname="Helvetica,Arial,sans-serif"]
subgraph cluster_0 {
style=filled;
color=lightgrey;
node [style=filled,color=white];
a0 -> a1 -> a2 -> a3;
label = "process #1";
}
subgraph cluster_1 {
node [style=filled];
b0 -> b1 -> b2 -> b3;
label = "process #2";
color=blue
}
start -> a0;
start -> b0;
a1 -> b3;
b2 -> a3;
a3 -> a0;
a3 -> end;
b3 -> end;
start [shape=Mdiamond];
end [shape=Msquare];
}You can include an optional width or/and height of the rendered SVG by including these after the ´´´ opening tag. You have the flexibility to specify an optional width and/or height for the rendered SVG by including these parameters immediately after the ´´´ opening tag on the same line as shown below.
´´´width=100 height=200
// https://graphviz.org/Gallery/directed/cluster.html
digraph G {
fontname="Helvetica,Arial,sans-serif"
node [fontname="Helvetica,Arial,sans-serif"]
edge [fontname="Helvetica,Arial,sans-serif"]
subgraph cluster_0 {
style=filled;
color=lightgrey;
node [style=filled,color=white];
a0 -> a1 -> a2 -> a3;
label = "process #1";
}
subgraph cluster_1 {
node [style=filled];
b0 -> b1 -> b2 -> b3;
label = "process #2";
color=blue
}
start -> a0;
start -> b0;
a1 -> b3;
b2 -> a3;
a3 -> a0;
a3 -> end;
b3 -> end;
start [shape=Mdiamond];
end [shape=Msquare];
}
Tables in Markdown are created using pipes | and hyphens - to define the structure of the table. It uses GitHub's Flavored Markdown, described here: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables. Here's an example:
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Row 1 | Data 1 | Data 2 |
| Row 2 | Data 3 | Data 4 |
| Row 3 | Data 5 | Data 6 |
You can align text to the left, right, or center of a column by placing colons : to the left, right, or on both sides of the hyphens in the header row as shown below.
| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| Row 1 | Data 1 | Data 2 |
| Row 2 | Data 3 | Data 4 |
You can include formatting such as links, inline code blocks, and text styling within your table:
| Left-aligned | Center-aligned | Right-aligned |
| :--- | :---: | ---: |
| Row1 *important* | `Data 1` | Data 2 |
| Row 2 | Data 3 **very important** | Data 4 |
You can find much more information on tables here: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables.
Horizontal rules can be used to create a visual separation between sections. They are created using three or more hyphens ---, asterisks ***, or underscores ___.
Introduction
---
Some text
***
Another text
___
Conclusion
