This repository contains the documentation for Octopus Deploy.

To contribute to documentation, read the following guide.

Conventions

Lower case and `-` delimited

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).

Headers

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)"
---

Title

Required. Used for the web page title tag <head><title>, displayed in the page content

Description

Required. Used for the meta description tag (<meta name="description" />). Keep the description under 160 characters. Read how to write a good description.

Position

Optional. Used for the position in the menu.

Version

Optional. The versions that this file applies to. This meatadata supports ranges, same syntax as nuget.

Version dropdown

The list of versions displayed on the dropdown are loaded from versions.json.

Include pre-release documentation

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:

URLs

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.

Index Pages

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.

Linking

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.

"In this section" area {#in-this-section}

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: true

The 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: true

Markdown

The site is rendered using markdig, Markdig supports GitHub Flavored Markdown as well as some extra syntax.

Lists

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.

Bullets

Example:

- Item 1
- Item 2

Rendered as:

Item 1
Item 2

Numbered

Example:

1. Item 1
1. Item 2

Rendered as:

Item 1
Item 2

Roman

Example:

i. Item 1
i. Item 2

Rendered as:

i. Item 1
ii. Item 2

Letters

Example:

a. Item 1
a. Item 2

Rendered as:

a. Item 1
b. Item 2

Code Samples

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:

Alerts

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>

Application Paths

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}}.

Headings

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.

Folder Version

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.

Includes

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.

Defining an include

Add a file anywhere in the docs repository that is suffixed with .include.md. For example, the file might be named theKey.include.md.

Using an include

Add the following to the markdown: !include <key>

Partials

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

Defining a partial

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.

Using a partial

Add the following to the markdown: !partial <key> (including the <>s)

Anchors

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)

Images

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

![Alt text](img.jpg "Optional title width=500")

With the minimal syntax being

![Alt text](img.jpg)

All images should have alt text.

Keep reading for a detailed explanation of the options available when working with images.

Image paths

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

Image versioning

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 sizing

Image size can be controlled by adding the text width=x to the end of the title

For example

![Alt text](/path/to/img.jpg "Optional title width=x")

With the minimal syntax being

![](/path/to/img.jpg "width=x")

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.

Redirects

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.

Useful Characters

Just go to http://htmlarrows.com/symbols/

More Information

Markdown Cheatsheet

jmalczak/docs

Conventions

Lower case and - delimited

Headers

Title

Description

Position

Version

Menu

Version dropdown

Include pre-release documentation

URLs

Index Pages

Linking

"In this section" area {#in-this-section}

Markdown

Lists

Bullets

Numbered

Roman

Letters

Code Samples

Alerts

Application Paths

ToC

Headings

Folder Version

Includes

Defining an include

Using an include

Partials

Defining a partial

Using a partial

Anchors

Images

Image paths

Image versioning

Image sizing

Redirects

Useful Characters

More Information

Lower case and `-` delimited