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
---Required. Used for the web page title tag <head><title>, displayed in the page content
Optional. Used for the meta description tag (<meta name="description" />).
Optional. Used for the position in the menu.
The menu is auto generated based on the git repo folder structure and title and position metadata.
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.
The site is rendered using markdig, Markdig supports GitHub Flavored Markdown as well as some extra syntax.
| language | key |
|---|---|
| c# | cs |
| xml | xml |
| no format | no-highlight |
| command line | bash |
| powershell | ps |
| json | json |
| sql | sql |
| f# | f# |
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.
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>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!
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 can be added using the following markdown syntax
With the minimal syntax being
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.
Just go to http://htmlarrows.com/symbols/