Markdown documents (such as a README.md) are rendered as
formatted text in VisualSVN Server's Web UI.
The Markdown formatting language has multiple variants, also known as Markdown flavors, which differ in their respective range of available formatting features. This article describes the range of formatting features that is supported by VisualSVN Server's Web UI, including all the supported syntax extensions. See the Markdown flavor supported by VisualSVN Server section below.
Additionally, the article describes how to best use the syntax for images, ordinary links and section links, when pointing to items inside or outside of the repository.
Markdown flavor supported by VisualSVN Server
You can use the following range of syntax to add styling/formatting within Markdown documents rendered in VisualSVN Server's Web UI:
- Standard Markdown syntax, which includes all the formatting features of the original Markdown language. The standard syntax is supported as defined by the CommonMark specification. For a quick introduction to the standard Markdown syntax, see the reference table.
- The following syntax extensions (or extended features), which go beyond the standard Markdown syntax:
Full support for the CommonMark specification of the standard Markdown syntax and for all the above-mentioned extensions requires VisualSVN Server 5.4.0 or later.
Syntax highlighting in fenced code blocks (extension)
Available since VisualSVN Server 5.4.0
In a fenced code block, you can add an optional language identifier immediately after the block's opening triple ticks, to enable syntax highlighting for this code block.
The language identifier can be specified as the name of the language (in
lower case without spaces) or as the language's typical file extension.
For example: c, c++ or cpp,
csharp or cs, golang or
go, java, javascript or
js, json, kotlin or
kt, python or py, etc.
Markdown example
```c
int main(int argc, char *argv[])
{
printf("Hello world!\n");
return 0;
}
```
How it will look
GFM alerts (extension)
Available since VisualSVN Server 5.4.0
This is an extension to the standard blockquote syntax in Markdown. The supported types of alerts are listed in the example below. In the rendered Markdown document, the text of an alert will be highlighted with a corresponding distinctive icon and color.
Markdown example
> [!NOTE]
> This is a note.
> [!TIP]
> This is a tip.
> [!IMPORTANT]
> This is important.
> [!WARNING]
> This is a warning.
> [!CAUTION]
> This is a caution.
How it will look
GFM strikethrough (extension)
While italic and bold formatting are part of the standard Markdown, the GFM strikethrough syntax is an extension.
Markdown example
Strike a ~~part of text out~~.
How it will look
GFM tables (extension)
The GFM tables extension lets you create tables in a Markdown document by
using pipes (|) to mark columns and 3 or more hyphens
(---) to mark the header row. Insert an empty line before a
table, because a table cannot interrupt a paragraph.
Markdown example
| First Header | Second Header | | --- | --- | | Cell contents | Cell contents | | Cell contents | Cell contents | | Perfect alignment... | ...is not mandatory |
How it will look
You can also use colons (:) in the header separator to define
the desired alignment of the content.
Markdown example
| Left Aligned | Centered | Right Aligned | | :--- | :---: | ---: | | Cell 1 | Cell 2 | Cell 3 | | Cell 4 | Cell 5 | Cell 6 |
How it will look
GFM task list (extension)
Available since VisualSVN Server 5.4.0
This extension to the unordered list syntax allows you to display a
list of items with checkboxes. In the rendered Markdown document, the
checkboxes are read-only. To tick or clear a box, commit a corresponding
change to the document. To tick a box, use a lower or upper case letter
x.
Markdown example
- [x] First thing to do
- [ ] Also need to do that
- [ ] Yet another task
How it will look
Images
In a Markdown document, you can insert an image by entering an exclamation
mark !, immediately followed by an image description
enclosed in square brackets [ ], immediately followed by the
path or URL to the image file enclosed in parentheses
( ). See the examples below.
Inserting an image using a relative path
Typically, to insert an image stored in the same repository as the Markdown document, you should provide the relative path to the image file. The path is relative to the Markdown document where you insert the image. For example:
The relative path to an image file is specified in the usual way. For an example of specifying a relative path, see the Specifying a relative path section for relative links.
Inserting an image using an absolute URL
Similarly, to display an image stored outside of the current repository, you need to specify the absolute URL of that external image file, for example:
Links
To insert a link, enter the text of the link, enclosing it in
square brackets [ ]. Immediately afterwards specify the
destination that the link should point to, enclosed in parentheses
( ). For example:
The following is the link to the [VisualSVN Home Page](https://www.visualsvn.com).
The destination can be either a relative path (for a relative link) or an absolute URL (for an absolute link). Choosing whether to use a relative or an absolute link depends on the use case, as described below.
Relative links
Available since VisualSVN Server 3.4.0
A relative link is a link that uses a relative path as the destination. The path is relative to the Markdown document where you insert the link:
This is a [link](path/to/file.md) to a Markdown document in the same repository.
You should normally use a relative link, when linking to another document, file or directory located in the same repository. Typically, use relative links to help users navigate between files that make up your documentation.
Specifying a relative path
The relative path that you point to is specified in the usual way. You can use the standard
relative path operands: ./ (the same directory, optional) and
../ (the higher-level directory).
For example, let's say you have README.md and
CHANGELOG.txt at the root of the trunk directory. And
User_Guide.md in the docs subdirectory of
trunk:
trunk
├── README.md
├── CHANGELOG.txt
└── docs
└── User_Guide.md
Then in README.md you might insert relative links to the
other two documents by entering their relative paths:
See the [Change Log](./CHANGELOG.txt) for the full list of changes. See the [User Guide](./docs/User_Guide.md) for detailed instructions.
And inside the User_Guide.md you might link to the
README.md document like this:
See the project's [README file](../README.md).
[Link text](<directory name/file name.md>)
Advantages of relative links
Relative links have the following important advantages:
- Relative links will continue to work in any branch, allowing you to always point to files or directories in the current branch.
-
Relative links are portable. Assuming that the file hierarchy of
the documentation is preserved, relative links will continue to work
even:
- if you copy this documentation to another repository or rename the current repository;
- if you change the domain name of your Subversion server;
- if you upload this documentation to other platforms that support Markdown rendering.
Absolute links
An absolute link is a link that uses an absolute URL as the destination. Absolute links are typically used to link to external web pages or to other web resources that are not located in the same repository. For example:
See the [VisualSVN Home Page](https://www.visualsvn.com).
If the link needs to point to an item (such as another document) located in the same repository, in most cases you should not use an absolute link, and should use a relative link instead.
However, you can use the absolute URL of a Markdown document to link to this document from outside of the repository. For example, the following is the absolute URL of a document about Python (from the Raspberry Pi Documentation) on the demo server:
https://demo-server.visualsvn.com/!/#raspberrypi-doc/view/head/usage/python/README.md
To get such an absolute URL, open the desired document in VisualSVN Server's Web UI and copy the URL from the web browser's address bar.
This also means that within a Markdown document you can use an absolute link to point to a document, file or directory located in another repository. For example:
[WebKit](https://demo-server.visualsvn.com/!/#webkit/view/head/trunk/ReadMe.md)
Section links (anchor links)
Available since VisualSVN Server 5.4.0
Section links (also known as anchor links) are a special case of Links and use essentially the same syntax. The only difference is that they allow you to link to a specific part of a target Markdown document. Typically, to a specific section heading. Section links can be especially useful for tables of contents and for navigating within large documents.
To link to a section heading, you can use its automatic heading ID, which is available for each Markdown heading in VisualSVN Server's Web UI. Note that the syntax to specify a heading ID in a link differs, depending on whether you use a relative link or an absolute URL.
Automatic heading IDs
Available since VisualSVN Server 5.4.0
In VisualSVN Server's Web UI, each heading in a Markdown document automatically gets a heading ID that you can link to.
The heading ID looks like the hyphen-separated lowercase words of
the heading, where any punctuation/non-word text is removed. For example,
if you have a heading that reads Main features, its heading ID will
be main-features.
To check the heading ID of a heading, hover the mouse cursor over
the desired heading in a rendered Markdown document in VisualSVN Server's
Web UI. In the URL that the web browser displays, the last part that comes
after ?a= is the heading ID.
main-features-1, main-features-2, etc.), which
allows you to precisely link to a specific section.
Relative links to section headings/anchors
Available since VisualSVN Server 5.4.0
You can use relative links to anchors (heading IDs) to do the following:
-
to link to a specific part (section heading) within the same Markdown
document. In this case, specify the link destination as a
hash sign
#followed by the desired heading ID:See the [Usage](#usage) section below.
-
to link to a specific part (section heading) in a different Markdown
document located in the same repository. In this case, specify
the link destination as the relative path to the
destination Markdown file, followed by a hash sign
#and the desired heading ID:See the [Installing on Windows](./README.md#installing-on-windows) section in the README.
[Möbius strip](#möbius-strip).
Absolute URLs of section headings/anchors
Available since VisualSVN Server 5.4.0
When linking between Markdown documents stored in the same repository, in most cases you should not use absolute links to anchors, and should use relative links to anchors instead. However, the absolute URL of an anchor allows you to link from outside of the repository to a specific section of a rendered Markdown document.
To copy the absolute URL of a heading in a Markdown document in the VisualSVN Server's Web UI, right-click the desired heading and select Copy link (or Copy link address, depending on your web browser) from the context menu.
In the VisualSVN Server's Web UI, the absolute URL of an anchor consists
of the absolute URL of a Markdown file, followed by ?a= and
then the heading ID. For example, the following is an absolute URL that
points to a section called Iteration in a README.md
document on the demo server:
https://demo-server.visualsvn.com/!/#raspberrypi-doc/view/head/usage/python/README.md?a=iteration
This also means that within a Markdown document you can use an absolute link to point to a particular section of a document located in another repository. For example:
See the [Reporting Bugs](https://demo-server.visualsvn.com/!/#webkit/view/head/trunk/ReadMe.md?a=reporting-bugs) section in ReadMe.md in the demo WebKit repository.
Reference link syntax
All the examples of ordinary links and section links above use the inline link syntax, but all the same remarks about the link destination are also applicable to the alternative reference link syntax.
When using this alternative, you can insert a link by entering a
link text enclosed in square brackets [ ], immediately
followed by a link label, which is also enclosed in square brackets
[ ]. Then elsewhere in the document you should specify a
matching link definition that provides the destination that
the link will point to, as in the example below:
See the [User Guide][1] for detailed instructions. See the [User Guide][my arbitrary label] for detailed instructions. Visit the [VisualSVN Home Page][2]. See the [Installing on Windows][3] section in the README. See the [Reporting Bugs][4] section in ReadMe.md in the demo WebKit repository. [1]: docs/User_Guide.md [my arbitrary label]: docs/User_Guide.md [2]: https://www.visualsvn.com [3]: README.md#installing-on-windows [4]: https://demo-server.visualsvn.com/!/#webkit/view/head/trunk/ReadMe.md?a=reporting-bugs
A link label can be any arbitrary string of text. The matching of link labels to link definitions is not case-sensitive.