Both the Octopus blog and the Octopus documentation are written in Markdown and rendered using markdig. Markdig supports GitHub Flavored Markdown as well as some extra syntax.
Filenames
Markdown filenames are lowercase and end with .md. Use hyphens to separate words:
- installation.md
- backup-and-restore.md
Files and directories
Directories must have an index file: index.md.
- directory/index.md
- directory/another-file.md
YAML headers
The Markdown files in the blog and docs have a YAML header:
YAML header (blog)
--- title: Runbooks best practices <!-- post title --> description: This post provides a step by step template you can use to generate high quality runbooks in Octopus author: email@octopus.com <!-- use your email address --> visibility: public <!-- options are public or private --> published: 2020-03-09 <!-- The date the post will be published --> metaImage: runbooks-best-practices.png bannerImage: runbooks-best-practices.png tags: <!-- see blog/tags.txt for a comprehensive list of tags --> - Product - Runbooks ---
YAML header (docs)
--- title: Installation <!-- page title --> description: How to install the Octopus Server. position: 20 <!-- position of the document relative to the other documents in the same section --> hideInThisSection: true <!-- Optional. Hides the automatic "In this section" section that lists child documents in the same section. Leave out if not needed. --> hideInThisSectionHeader: true <!-- Optional. Only hides the header for the "In this section" section --> ---
Table of contents
Use !toc within the body of a page to include a table of contents that lists the sections on the current page.
Headings
Use ## to create h2 headers and ### to create h3 headers.
The first header you include on a page must be a h2 header. The title of the page comes from the title in the YAML block.
Formatting text
Bold text with ** on both sides of text to create **bold text**: bold text.
Italicize text with * on both sides of text to create *emphasized text*: emphasized text.
Images
Image filenames must be all lowercase, with no spaces or special characters other than hyphens.
Add images in the same directory as the file that references the image.
Images are added to documents with the following syntax:
Images should include alt text for accessibility:
Images can also include caption text for additional context or info:
*Caption text*
A screen reader will read both the alt text and the caption, so make them different. Alt text should be more detailed than the caption.
Control the size of the image in pixels by adding: width=500:
Lists
Bullet lists are written with a hyphen at the beginning of the line:
- Item 1
- Item 2
Which is rendered as:
- Item 1
- Item 2
Numbered lists are written with a number at the beginning of the line. The numbers do not need to increment as this will happen automatically:
1. Item 1
2. Item 2
Which is rendered as:
- Item 1
- Item 2
You can nest lists by adding three spaces before the nested list items.
1. Item 1
1. Item 1.1
2. Item 1.2
2. Item 2
Which is rendered as:
- Item 1
- Item 1.1
- Item 1.2
- Item 2
If you include an interruption between list items, you need to resume the list with the number the list should restart from:
1. Item 1
1. Item 2
A break in the list.
3. Item 3
4. Item 4
Which is rendered as:
- Item 1
- Item 2
A break in the list.
3. Item 3
4. Item 4
Tables
Tables are written in the following following way:
| Header 1 | Header 2 | Header 3 | Header 4 | Header 4 |
|---|---|---|---|---|
| Row 1 Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 4 |
| Row 2 Cell 1 | Cell 2 | Cell 3 | Cell 4 | Cell 4 |
There are generators online you can use to make this process a bit easier, for example, Table generator.
Links
To link to other pages in the documentation, use the following syntax (include the full filename and extension):
For more information, see the [installation page](/docs/installation/index.md) and review the [installation requirements](/docs/installation/requirements.md).
This will link to https://www.octopus.com/docs/installation and https://www.octopus.com/docs/installation/requirements.
To link to other posts in the blog, include the full URL:
This is part one in a series of posts, read [part two](https://www.octopus.com/blog/blog-title-part-two).
This links to https://www.octopus.com/blog/blog-title-part-two.
Anchor links
To link to a specific section in a document, add the section heading as an anchor and replace the spaces with hyphens:
Octopus can be installed on these versions of [Windows Server](docs/installation/requirements.md#windows-server).
This will link to https://octopus.com/docs/installation/requirements#windows-server
If you'd like to control the anchor text (to ensure it doesn't change even if the title does), use the following syntax:
## Windows Server {#windows-server}
Special characters will break the anchor text, so don't include special characters in the anchor.
Navigation paths
When instructing users to navigate through multiple options in the UI, use the following syntax:
{% raw %}{{ infrastructure,Deployment Targets }}{% endraw %}
Which will be rendered:
Infrastructure ➜ Deployment Targets
Code samples
Use GitHub-style fenced code blocks. For example:
```ps
Write-Host "Hello"
```
If your example uses multiple languages or files, you can combine them together to add tab headings:
```ps PowerShell
Write-Host "Hello"
```
```cs C
# Console.WriteLine("Hello");
```
Snippets are highlighted by Highlight.js
If no language is defined, highlightjs will guess the language, and it regularly gets it wrong.
Call-outs
To create a call-out that draws the reader's attention, use the following syntax:
:::warning
This release includes the following breaking changes...
:::
This will be rendered as:
<div class="alert alert-warning">
<p>This release includes the following breaking changes...</p>
</div>
There are several keys, each of which map to a different colored alert:
- success = green
- hint= blue
- warning= yellow
- problem=red
Call-outs are added through bootstrap alerts.
Block quotes
To include block quotes use the following syntax: > This is a quote.
Reuse text
To create reusable text that is automatically added to any document that references it, add the text to a new file and save the file with a key followed by .include.md. For instance, latest-version.include.md, and save the file to the docs/shared-content/ or blog/shared-content/ directory respectively:
The latest version of Octopus Deploy is 2020.1
If the complete filename is latest-version.include.md, to include the text in other documents, use the following everywhere you want the text to be included:
!include <latest-version>
When you use an include file in this way, you only need to update the text in one file and the updated text will be included anywhere it is referenced.
Referencing Docker images
When referencing docker images, use the syntax:
!docker-image <org/image:tag>
This will be replaced with the most recently published version of the image.
Example 1 - with tags
!docker-image <octopusdeploy/octo:alpine>
Will be replaced with:
octopusdeploy/octo:6.17.3-alpine
Example 2 - without tags
!docker-image <octopusdeploy/octo>
Will be replaced with:
octopusdeploy/octo:6.17.3
Link to the Octopus Guides
The Octopus Guides combine content to allow users to specify their entire CI/CD pipeline and access a guide for their specific pipeline. It is sometimes helpful to link to the guides with specific options pre-defined rather than the default options.
You can create the links to use by adding query parameters to the URL for the guides https://www.octopus.com/docs/guides:
- Application: add ?application=PHP:
- https://www.octopus.com/docs/guides?application=PHP
- Build server: add ?build-server=jenkins:
- https://www.octopus.com/docs/guides?buildServer=Jenkins
- Source control: sourceControl=TFVC:
- https://octopus.com/docs/guides?sourceControl=TFVC
- Package repository: ?packageRepository=Artifactory:
- https://octopus.com/docs/guides?packageRepository=Artifactory
- Destination: ?destination=NGINX:
- https://octopus.com/docs/guides?destination=NGINX
If you'd like to pre-fill more than one option, add multiple queries parameters to the URL:
https://octopus.com/docs/guides?application=PHP&buildServer=TeamCity&destination=NGINX
Redirects
If you delete or rename a file in either the docs or blog repos, you must add a redirect for that file otherwise publishing will fail.
Redirects are added to docs/redirects.txt and blog/redirects.txt files respectively.
The redirects.txt file looks like this:
from-file-path -> to-file-path #DO NOT DELETE THIS LINE
docs/page1.md -> docs/page2.md
In the above example, /docs/page1 is redirected to /docs/page2.
Add your redirect to the end of the file, after the redirect is added, the original file (page1) needs to be deleted from the repo.