(GH-1932) Linting and ordering of build server section

docs/input/docs/build-server-support/build-server/appveyor.md

@@ -1,7 +1,11 @@
-# AppVeyor Setup
-AppVeyor is the first build server which has a setup helper built into `GitVersion init`.
+---
+Order: 10
+Title: AppVeyor Setup
+---
+AppVeyor is the first build server which has a setup helper built into
+`GitVersion init`.
 
- 1. Run `GitVersion init`
- 2. Choose `Setup build scripts` (currently option 7, but that could change)
- 3. Choose `AppVeyor`
- 4. Follow the prompts to generate an AppVeyor.yml file which works nicely with GitVersion
+1. Run `GitVersion init`
+2. Choose `Setup build scripts` (currently option 7, but that could change)
+3. Choose `AppVeyor`
+4. Follow the prompts to generate an AppVeyor.yml file which works nicely with GitVersion

docs/input/docs/build-server-support/build-server/azure-devops.md

@@ -1,42 +1,81 @@
-# TFS Build or Azure DevOps Pipeline Setup
+---
+Order: 20
+Title: Azure DevOps or TFS Build Pipeline SetupUsage
+---
+
 ## Basic Usage
-In Azure DevOps Pipeline (the web based build system) you can call GitVersion either using the Command Line build step or install an extension / custom build step. The custom build step requires a one-time setup to import the GitVersion task into your TFS or Azure DevOps Pipeline instance.
+
+In Azure DevOps Pipeline (the web based build system) you can call GitVersion
+either using the Command Line build step or install an extension / custom build
+step. The custom build step requires a one-time setup to import the GitVersion
+task into your TFS or Azure DevOps Pipeline instance.
 
 ## Executing GitVersion
+
 ### Using GitVersion with the MSBuild Task NuGet Package
-1. Add the [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/) NuGet package to your projects.
 
-See [MSBuild Task](/usage/msbuild-task) for further instructions how to use the MS Build Task.
+1. Add the [GitVersionTask](https://www.nuget.org/packages/GitVersionTask/)
+NuGet package to your projects.
+
+See [MSBuild Task](/usage/msbuild-task) for further instructions how to use the
+MS Build Task.
 
 ### Using GitVersion with the Command Line build step
-1. Make sure to have GitVersion.exe under version control. There exists also a [Chocolatey package](https://chocolatey.org/packages/GitVersion.Portable) for installing GitVersion.exe on build agents.
-2. Add a Command Line build step to your build definition. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
+
+1. Make sure to have GitVersion.exe under version control. There exists also a
+[Chocolatey package](https://chocolatey.org/packages/GitVersion.Portable) for
+installing GitVersion.exe on build agents.
+2. Add a Command Line build step to your build definition. You'll probably want
+to drag the task to be at or near the top to ensure it executes before your
+other build steps.
 3. Set the Tool parameter to `<pathToGitVersion>\GitVersion.exe`.
 4. Set the Arguments parameter to `/output buildserver /nofetch`.
-5. If you want the GitVersionTask to update AssemblyInfo files add `updateAssemblyInfo true` to the Arguments parameter.
-6. If you want to update the build number you need to send a [logging command](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/commands.md) to TFS.
+5. If you want the GitVersionTask to update AssemblyInfo files add
+`updateAssemblyInfo true` to the Arguments parameter.
+6. If you want to update the build number you need to send a
+[logging command](https://github.com/Microsoft/azure-pipelines-tasks/blob/master/docs/authoring/commands.md)
+to TFS.
 
 ### Using the custom GitVersion build step
+
 #### Installing
+
 ##### Installing the extension
-For Visual Studio Team Service or TFS 2015 Update 2 or higher it is recommonded to install the GitVersion extension:
-1. Install the [GitVersion Extension](https://marketplace.visualstudio.com/items?itemName=gittools.gitversion).
+
+For Visual Studio Team Service or TFS 2015 Update 2 or higher it is recommended
+to install the GitVersion extension:
+
+1. Install the
+[GitVersion Extension](https://marketplace.visualstudio.com/items?itemName=gittools.gitversion).
 
 ##### Manually installing/updating the custom build step
-If you run TFS 2015 RTM or Update 1 or don't want to install the GitVersion extension you can install the build task manually:
+
+If you run TFS 2015 RTM or Update 1 or don't want to install the GitVersion
+extension you can install the build task manually:
+
 1. Install the `tfx` command line tool as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/README.md#install).
 2. For TFS 2015 On-Prem configure Basic Authentication in TFS as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/docs/configureBasicAuth.md).
-3. Download the GitVersion TFS build task from the latest release on the [GitVersion releases page](https://github.com/GitTools/GitVersion/releases) and unzip.
+3. Download the GitVersion TFS build task from the latest release on the
+[GitVersion releases page](https://github.com/GitTools/GitVersion/releases) and
+unzip.
 4. Run `tfx login` as shown [here](https://github.com/Microsoft/tfs-cli/blob/master/README.md#login).
-5. From the directory outside of where you unzipped the task, run `tfx build tasks upload --task-path .\GitVersionVsixTask --overwrite` where GitVersionVsixTask is the directory containing the files.
+5. From the directory outside of where you unzipped the task, run
+`tfx build tasks upload --task-path .\GitVersionVsixTask --overwrite` where
+GitVersionVsixTask is the directory containing the files.
 6. It should successfully install.
 
 #### Using the GitVersion custom build step
-From a TFS build definition, select "Add a Step" and then in the Build category, choose GitVersion and click Add. You'll probably want to drag the task to be at or near the top to ensure it executes before your other build steps.
 
-If you want the GitVersionTask to update AssemblyInfo files, check the box in the task configuration. For advanced usage, you can pass additional options to the GitVersion exe in the Additional arguments section.
+From a TFS build definition, select "Add a Step" and then in the Build category,
+choose GitVersion and click Add. You'll probably want to drag the task to be at
+or near the top to ensure it executes before your other build steps.
+
+If you want the GitVersionTask to update AssemblyInfo files, check the box in
+the task configuration. For advanced usage, you can pass additional options to
+the GitVersion exe in the Additional arguments section.
 
-The Azure DevOps Pipeline build step can update your build number with GitVersion variables. See below for details.
+The Azure DevOps Pipeline build step can update your build number with
+GitVersion variables. See below for details.
 
 #### Using Pipelines yaml
 
@@ -45,7 +84,7 @@ Add the following yaml task and variable to your `azure-pipelines.yml` file:
 ```yml
 variables:
   GitVersion.SemVer: ''
-   
+
 steps:
 - task: gittools.gitversion.gitversion-task.GitVersion@5
   displayName: gitversion
@@ -54,7 +93,9 @@ steps:
     configFilePath: GitVersion.yml
 ```
 
-You can now use the `GitVersion.SemVer` environment variable in any subsequent tasks to refer to the semantic version number for your build. For example, you can build your dotnet core application with a semantic version number like so:
+You can now use the `GitVersion.SemVer` environment variable in any subsequent
+tasks to refer to the semantic version number for your build. For example, you
+can build your dotnet core application with a semantic version number like so:
 
 ```yml
 - task: DotNetCoreCLI@2
@@ -69,34 +110,56 @@ You can now use the `GitVersion.SemVer` environment variable in any subsequent t
 ```
 
 ## Running inside TFS
+
 ### Using the GitVersion Variables
-GitVersion passes variables in the form of `GitVersion.*` (Eg: `GitVersion.Major`) to TFS Build and also writes `GITVERSION.*` (Eg: `GITVERSION.MAJOR`) environment variables that are available for any subsequent build step.
 
-To use these variables you can just refer to them using the standard variable syntax. For instance `$(GitVersion.NuGetVersion)` in your nuget pack task to set the version number. Since update 1 there are no known limitations.
+GitVersion passes variables in the form of `GitVersion.*` (Eg:
+`GitVersion.Major`) to TFS Build and also writes `GITVERSION.*`
+(Eg: `GITVERSION.MAJOR`) environment variables that are available for any
+subsequent build step.
 
-See [Variables](/more-info/variables/) for an overview of available variables.
+To use these variables you can just refer to them using the standard variable
+syntax. For instance `$(GitVersion.NuGetVersion)` in your nuget pack task to set
+the version number. Since update 1 there are no known limitations.
 
+See [Variables](/more-info/variables/) for an overview of available variables.
 
 #### Using GitVersion variables in build name
-To use GitVersion's variables in the build name, just add them in the form `$(GITVERSION_FullSemVer)` into the Build definition's build number string. Then just ensure GitVersion is called with
-`/output buildserver` and it will replace those variables with the calculated version.
-The TFS GitVersion Build Step (above) handles this too, so if you're already using that, there's nothing extra to configure.
+
+To use GitVersion's variables in the build name, just add them in the form
+`$(GITVERSION_FullSemVer)` into the Build definition's build number string. Then
+just ensure GitVersion is called with `/output buildserver` and it will replace
+those variables with the calculated version.  The TFS GitVersion Build Step
+(above) handles this too, so if you're already using that, there's nothing extra
+to configure.
 
 If GitVersion does not find any substitutions it will just default to using `FullSemVer`
 
-**IMPORTANT:** If you currently use `$(rev:.r)` in your build number, that won't work correctly if you
-use GitVersion variables as well due to the delayed expansion of the GitVersion vars. Instead,
-You might be able to use `$(GitVersion_BuildMetaData)` to achieve a similar result.
-See [Variables](/more-info/variables/) for more info on the variables.
+**IMPORTANT:** If you currently use `$(rev:.r)` in your build number, that won't
+work correctly if you
+use GitVersion variables as well due to the delayed expansion of the GitVersion
+vars. Instead, you might be able to use `$(GitVersion_BuildMetaData)` to achieve
+a similar result.  See [Variables](/more-info/variables/) for more info on the
+variables.
 
 #### Known limitations
-* If you are using on premises TFS, make sure you are using at least **TFS 2015 Update 1**, otherwise a few things will not work.
-* Installing the extension on an on premise TFS requires at least TFS 2015 Update 2.
-* You need to make sure that all tags are fetched for the Git repository, otherwise you may end with wrong versions (e.g. `FullSemVer` like `1.2.0+5` instead of `1.2.0` for tagged releases)
-Just checking the `Clean Repository` check box in the build definition settings might not be enough since this will run a `git clean -fdx/reset --hard` without fetching all tags later.
-You can force deletion of the whole folder and a re-clone containing all tags by settings the variable `Build.Clean` to `all`.
-This will take more time during build but makes sure that all tags are fetched.
-In the future it is planned to allow using `git.exe` instead of current `libgit2sharp` for syncing the repos which might allow other possibilities to solve this issue.
-For details see this [GitHub issue](https://github.com/Microsoft/azure-pipelines-tasks/issues/1218).
-* If running a build for a certain commit (through passing the commit SHA while queueing the build) all tags from the repository will be fetched, even the ones newer than the commit.
-This can lead to different version numbers while re-running historical builds.
+
+* If you are using on premises TFS, make sure you are using at least
+**TFS 2015 Update 1**, otherwise a few things will not work.
+* Installing the extension on an on premise TFS requires at least TFS 2015
+Update 2.
+* You need to make sure that all tags are fetched for the Git repository,
+otherwise you may end with wrong versions (e.g. `FullSemVer` like `1.2.0+5`
+instead of `1.2.0` for tagged releases)  Just checking the `Clean Repository`
+check box in the build definition settings might not be enough since this will
+run a `git clean -fdx/reset --hard` without fetching all tags later. You can
+force deletion of the whole folder and a re-clone containing all tags by
+settings the variable `Build.Clean` to `all`. This will take more time during
+build but makes sure that all tags are fetched. In the future it is planned to
+allow using `git.exe` instead of current `libgit2sharp` for syncing the repos
+which might allow other possibilities to solve this issue. For details see this
+[GitHub issue](https://github.com/Microsoft/azure-pipelines-tasks/issues/1218).
+* If running a build for a certain commit (through passing the commit SHA while
+queueing the build) all tags from the repository will be fetched, even the ones
+newer than the commit.  This can lead to different version numbers while
+re-running historical builds.

docs/input/docs/build-server-support/build-server/bamboo.md

@@ -1,20 +1,28 @@
-# Bamboo
-If you use Bamboo then you will have to use GitVersion from the command line, as there is no actively supported app.
-You can use the "Inject Bamboo Variables" task to read the GitVersion output back into Bamboo.
-Below is a Linux example using the [.NET Core GitVersion global tool](https://www.nuget.org/packages/GitVersion.Tool/).
+---
+Order: 30
+Title: Bamboo
+---
+
+If you use Bamboo then you will have to use GitVersion from the command line, as
+there is no actively supported app.  You can use the "Inject Bamboo Variables"
+task to read the GitVersion output back into Bamboo.  Below is a Linux example
+using the [.NET Core GitVersion global tool](https://www.nuget.org/packages/GitVersion.Tool/).
 
 ## Example
 
-### Task: Script 
+### Task: Script
 
 **Script body**
+
 ```bash
 ~/.dotnet/tools/dotnet-gitversion > gitversion.txt
 sed -i '1d;26d;s/  //;s/"//g;s/,//;s/:/=/' gitversion.txt
 ```
 
 ### Task: Inject Bamboo variables Configuration
+
 **Required Properties**
+
 - __Path to properties file__: gitversion.txt
 - __Namespace__: GitVersion
 - __Scope of the Variables__: Result

docs/input/docs/build-server-support/build-server/continua.md

@@ -1,33 +1,45 @@
-# Continua CI Setup
+---
+Order: 40
+Title: Continua CI Setup
+---
 
 This guide explains how to run GitVersion inside [Continua CI](https://www.finalbuilder.com/continua-ci).
 
 ## Assumptions
-This guide assumes a few variables are present in the configuration. Note that this example uses `Catel` as repository name, but it should be replaced by the name of the repository where GitVersion is runnign against.
 
-* RepositoryBranchName => $Source.Catel.BranchName$ 
-* RepositoryCommitId => $Source.Catel.LatestChangeset.Id$ 
+This guide assumes a few variables are present in the configuration. Note that
+this example uses `Catel` as repository name, but it should be replaced by the
+name of the repository where GitVersion is running against.
+
+* RepositoryBranchName => $Source.Catel.BranchName$
+* RepositoryCommitId => $Source.Catel.LatestChangeset.Id$
 * RepositoryName => Catel
 * RepositoryName => $Source.Catel.Path$
-* RepositoryUrl => $Source.Catel.Url$ 
+* RepositoryUrl => $Source.Catel.Url$
 
-It also requires a few variables which will automatically be filled by GitVersion. The example below are just a few, any of the GitVersion variables written to the output can be used.
+It also requires a few variables which will automatically be filled by
+GitVersion. The example below are just a few, any of the GitVersion variables
+written to the output can be used.
 
 * GitVersion_FullSemVer
 * GitVersion_MajorMinorPatch
 * GitVersion_NuGetVersion
 
-You also need to add a property collector for the agents to detect the GitVersion tool on the agents:
+You also need to add a property collector for the agents to detect the
+GitVersion tool on the agents:
 
 * Namespace => GitVersion
 * Run On => Agent
 * Type => Path Finder Plugin
 * Property Name => Path
 * Executable => GitVersion.exe
-* Search paths => your installation folder (e.g. `C:\Tools\GitVersion` or if you are using Chocolatey `C:\ProgramData\chocolatey\lib\GitVersion.Portable\tools`)
+* Search paths => your installation folder (e.g. `C:\Tools\GitVersion` or if you
+are using Chocolatey `C:\ProgramData\chocolatey\lib\GitVersion.Portable\tools`)
 
 ## Basic Usage
-To run GitLink inside [Continua CI](https://www.finalbuilder.com/continua-ci), follow the steps below:
+
+To run GitLink inside [Continua CI](https://www.finalbuilder.com/continua-ci),
+follow the steps below:
 
 * Add a new `Execute Program` step to a stage
 * In the `Execute Program` tab, set the following values:
@@ -41,5 +53,5 @@ To run GitLink inside [Continua CI](https://www.finalbuilder.com/continua-ci), f
   * Check program exit code: checked
   * Exit code must be: equal to
   * Exit code: 0
-  
+
 Now GitVersion will automatically run and fill the `GitVersion_` variables.

docs/input/docs/build-server-support/build-server/gitlab.md

@@ -1,3 +1,7 @@
-# GitLab CI
+---
+Order: 50
+Title: GitLab CI
+---
 
-To use GitVersion with GitLab CI, either use the [MSBuild Task](/usage/msbuild-task) or put the GitVersion executable in your runner's `PATH`.
+To use GitVersion with GitLab CI, either use the [MSBuild Task](/usage/msbuild-task)
+or put the GitVersion executable in your runner's `PATH`.

docs/input/docs/build-server-support/build-server/jenkins.md

@@ -1,18 +1,26 @@
-# Jenkins Setup
+---
+Order: 60
+Title: Jenkins Setup
+---
 
-Injecting environment variables is not supported in Jenkins natively, but Jenkins plugins exist that provide this functionality. Of these plugins [EnvInject] appears to be the most popular with over 20k downloads per month.
+Injecting environment variables is not supported in Jenkins natively, but
+Jenkins plugins exist that provide this functionality. Of these plugins
+[EnvInject] appears to be the most popular with over 20k downloads per month.
 
-To inject the GitVersion variables as environment variables for a build job using  [EnvInject], do the following:
+To inject the GitVersion variables as environment variables for a build job
+using [EnvInject], do the following:
 
- 1. Add an **Execute Windows batch command** build step with *Command*:
+1. Add an **Execute Windows batch command** build step with *Command*:
     `gitversion /output buildserver`
- 1. Add an **Inject environment variables** build step and use value 'gitversion.properties' for the *Properties File Path* parameter 
+1. Add an **Inject environment variables** build step and use value
+'gitversion.properties' for the *Properties File Path* parameter
 
 This assumes GitVersion.exe is available on the command line.
 
-You can verify correct injection of environment variables by adding another "Execute Windows batch command" build step with the following *Command*:
+You can verify correct injection of environment variables by adding another
+"Execute Windows batch command" build step with the following *Command*:
 
-```
+```shell
 @echo Retrieving some GitVersion environment variables:
 @echo %GitVersion_SemVer%
 @echo %GitVersion_BranchName%
@@ -21,4 +29,4 @@ You can verify correct injection of environment variables by adding another "Exe
 @echo %GitVersion_Sha%
 ```
 
-  [EnvInject]: https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin
+[EnvInject]: https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin