This repository contains the documentation for Octopus Deploy.
To contribute to documentation, read the following guide.
All content files (.md, .png, .jpg etc) and directories must be lower case.
All links pointing to them must be lower case.
Use a dash (-) to delimit filenames (e.g. specify-endpoint-name.md).
Each document has a header. It is enclosed by --- and is defined in a YAML document format.
The GitHub UI will correctly render YAML.
For example:
---
title: Getting started
description: From 0 to deployed, this guide walks you through getting started with Octopus.
position: 0
version: "[3.0,4.0)"
---Required. Used for the web page title tag <head><title>, displayed in the page content
Required. Used for the meta description tag (<meta name="description" />).
Keep the description under 160 characters.
Read how to write a good description.
Optional. Used for the position in the menu.
Optional. The versions that this file applies to. This meatadata supports ranges, same syntax as nuget.
The menu is auto generated based on the git repo folder structure and title and position metadata.
The list of versions displayed on the dropdown are loaded from versions.json.
Support to publish pre-release versions of documentation. This is useful when we planning a new release or we are releasing betas or RCs.
To use this functionality all you need to do is add the pre-release version to the versions.json file versions array, and leave the default the same version, the example above adds 3.13 pre-release:
{
"versions": [
"3.6",
"3.7",
"3.8",
"3.9",
"3.10",
"3.11",
"3.12",
"3.13"
],
"default": "3.12"
}Once this is done, the version selector on the website by default still displays the latest, but the new pre-release is now listed above:
And when selected a banner tells the user that they are seeing a "preview" of the documentation:
The directory structure where a .md exists is used to derive the URL for that document.
So a file existing at /docs/myfolder/mypage.md will have a URL of https://octopus.com/docs/myfolder/mypage.
One exception to the URL rule is when a page is named index.md. In this case the index.md is omitted in the URL and only the directory structure is used.
So a file existing at /docs/myfolder/index.md will have a URL of https://octopus.com/docs/myfolder.
Links to other documentation pages should be relative and contain the .md extension.
The .md allows links to work inside the GitHub web UI. The .md will be trimmed when they are finally rendered.
Index pages (index.md) automatically have a "In this section" section added to them (bottom of the content), which lists all child pages in the folder.
If the page does not need this section, you can opt out by adding the following metadata to the yaml:
hideInThisSection: trueThe rendering of "In this section" section contains a header, if you need to omit this header (but still want it to contain the list of child pages):
hideInThisSectionHeader: trueThe site is rendered using markdig, Markdig supports GitHub Flavored Markdown as well as some extra syntax.
Lists can be created using a few different styles, please be aware that Roman and Letters won't render properly in github (this is a markdig extension).
To ensure the list items are correctly formmatted it is recommended to not number the items, instead let the markdown renderer do that job automatically, so for a numeric list use one 1s for a letter list use one a.s and for a roman list use only is.
Example:
- Item 1
- Item 2Rendered as:
- Item 1
- Item 2
Example:
1. Item 1
1. Item 2Rendered as:
- Item 1
- Item 2
Example:
i. Item 1
i. Item 2Rendered as:
i. Item 1
ii. Item 2
Example:
a. Item 1
a. Item 2Rendered as:
a. Item 1
b. Item 2
Use GitHub-style fenced code blocks. Example:
```powershell
Write-Host "Hello"
```
If your example uses multiple languages or files, you can combine them together and add tab headings - they will be rendered as tabs:
```powershell PowerShell
Write-Host "Hello"
```
```c# C#
Console.WriteLine("Hello");
```
Snippets are highlighted by Highlight.js
| language | key |
|---|---|
| c# | cs |
| xml | xml |
| no format | no-highlight |
| command line | bash |
| powershell | ps |
| json | json |
| sql | sql |
| f# | fsharp |
| text | text |
Always use fenced code blocks with a language. If no language is defined then highlightjs will guess the language and it regularly gets it wrong. Example:
Sometimes it is necessary to draw attention to items you want to call out in a document. This is achieved through bootstrap alerts https://getbootstrap.com/components/#alerts There are several keys each of which map to a different colored alert
| Key | Color |
|---|---|
success |
green |
hint |
blue |
warning |
yellow |
problem |
red |
Keys can be used in the following manner
:::hint
**Guess what**
The number is 45.
:::will be rendered as
<div class="alert alert-info">
<p><strong>Guess what</strong></br>
The number is 45.</p>
</div>In order to be consistent when referencing certain areas of the application we have created a markdown extension to render application paths. To render an application path use the following syntax:
{{my,application,path}} or {{my>application>path}}The , or > are the separator characters.
Example:
To enable Docker in your Octopus Server instance, toggle the feature on via {{Configuration,Features,Docker}}.Table of contents can be added to any page anywhere by adding !toc to the markdown. The table of contents lists all headers (H1, H2 etc) in the current document (see In This Section for child page links on index pages).
The first (and all top level) headers in a .md page should be a h2 (i.e. ##) with sub-headings under it being h3, h4, etc.
DO NOT skip headers, eg. h1 > h2 > h4, not valid!
You must also separate the '##' and the heading with a space. If you don't the heading will render correctly in the Preview in GitHub, and in many other tools, but will not render correctly on the docs site.
You can version the content of a whole folder by versioning the index.md for the folder.
Example:
If we want to hide the whole docker doco for versions prior to v3.4, we can add version: [3.4,) to the docs/guides/docker/index.md metadata.
This will exclude docker content from all versions prior to v3.4.
Sometimes you need to duplicate content in multiple pages, this is where includes are handy. Markdown includes are pulled into the document prior to passing the content through the markdown conversion.
Add a file anywhere in the docs repository that is suffixed with .include.md. For example, the file might be named theKey.include.md.
Add the following to the markdown: !include <key>
Partials are version specific files that contain markdown. Markdown partials are pulled into the document prior to includes, so this means you can add includes to partials. They are only rendered in the target page when the version filter matches the convention for a give file.
Partial Convention: filePrefix_key_version.partial.md
Add a file in the same folder as the page where you will use the partial to the docs repository that is named fileName_key_version.partial.md. For example, the file might be named getting-started_theKey_2.0.partial.md.
Add the following to the markdown: !partial <key> (including the <>s)
One addition to standard markdown is the auto creation of anchors for headings.
So if you have a heading like this:
## My Heading
it will be converted to this:
<h2>
<a name="my-heading"/>
My Heading
</h2>
Which means elsewhere in the page you can link to it with this:
[Goto My Heading](#My-Heading)
[Goto a different page](/docs/getting-started.md#My-Heading)
You have a few options:
- Put your image in the same folder as the markdown file;
- For shared images, put your image in the images folder;
- For internet images, just reference it remembering to use the
https://scheme;
Images can be added using the following markdown syntax
With the minimal syntax being
All images should have alt text.
Keep reading for a detailed explanation of the options available when working with images.
Paths to internal images need to:
- be relative or absolute
- all lower case
- can include
.and- - can also have version range, see image versioning
Example /docs/images/naked-scripting/transferpackage-transfer.png
Images can be versioned. To version an image you need to include the default image and the versioned images.
The convention is imagename_version.ext
Here is an example:
Let's say we want to display a different versions of myimage.png for v1.0 and v2.0 and we are currently on version 3.0.
All we need to do is create the new image and name it with a version range myimages_[1.0,3.0).png.
So in the end you have 2 images, myimage.png and myimages_[1.0,3.0).png.
All versioned images need to be in the same folder as the default image.
Image size can be controlled by adding the text width=x to the end of the title
For example
With the minimal syntax being
This will result in the image being re-sized with the following parameters
width="x" height="auto"
It will also wrap the image in a clickable lightbox so the full image can be accessed.
When a file is deleted, renamed or versioned you need to consider adding a redirect for that file. Redirects are added to redirects.txt. This file looks something like:
from-file-path -> to-file-path #DO NOT DELETE THIS LINE
docs/page1.md -> docs/page3.md
In the above example, /docs/page1 is redirected to /docs/page2
Once a redirect is added, the source file needs to be deleted from the repo, or in the case of docs, if the file is versioned, the version range needs to exclude the versions that want to be redirected, if all versions are to be redirected then the file needs to be deleted.
The destination is validated and needs to exist.
If a file is deleted or the version range no longer includes that file, a redirect need to exist for it, otherwise the sync fails.
Just go to http://htmlarrows.com/symbols/