Merge pull request #1202 from arturcic/feature/docs-linting

Add markdown linting

.azure/ci.yml

@@ -42,7 +42,7 @@ jobs:
         npm install
       displayName: 'Install dependencies'
     - pwsh: |
-        npm run lint:check && npm run format:check
+        npm run lint:check && npm run format:check && npm run mdlint:check
       displayName: 'Check code formatting'
     - pwsh: |
         npm run build:tools

.editorconfig

@@ -1,4 +1,4 @@
-# http://editorconfig.org
+# https://editorconfig.org
 root = true
 
 [*]

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
         npm install
       name: Install dependencies
     - run: |
-        npm run lint:check && npm run format:check
+        npm run lint:check && npm run format:check && npm run mdlint:check
       name: Check code formatting
     - run: |
         npm run build:tools

.markdownlint.yml

@@ -0,0 +1,10 @@
+MD033:
+  allowed_elements:
+  - details
+  - summary
+  - b
+  - i
+MD013: false
+
+MD041:
+  level: 1

dist/azure/overview.md

@@ -1,4 +1,6 @@
-Versioning when using Git, solved. GitVersion looks at your Git history and works out the [semantic version](http://semver.org) of the commit being built.
+# GitTools bundle for Azure Pipelines
+
+Versioning when using Git, solved. GitVersion looks at your Git history and works out the [semantic version](https://semver.org) of the commit being built.
 
 It works with most branching strategies but has been designed mainly around GitFlow and GitHubFlow (pull request workflow). The calculated version numbers can then be accessed through variables such as `$(GitVersion.FullSemVer)` and `$(GitVersion.SemVer)`. It is also very configurable to allow it to work with most release workflows!
 

docs/cloning.md

@@ -1,4 +1,6 @@
-In order for the gitversion to properly work you need to clone the repository with the entire history:
+# Cloning
+
+In order for the GitVersion to properly work you need to clone the repository with the entire history:
 
 ```yaml
 # GitHub Actions syntax

docs/examples/azure/gitreleasemanager/setup.md

@@ -1,3 +1,9 @@
+# Setup GitReleaseManager Task (gitreleasemanager/setup) Usage Examples
+
+Find out how to use the **gitreleasemanager/setup** task using the examples below.
+
+> The examples use version _2.0.1_ of the GitReleaseManager Setup task.  It is recommended to use the latest released version in your own workflows.
+
 ## Inputs
 
 The Setup GitReleaseManager action accepts the following inputs:

docs/examples/azure/gitversion/execute/usage-examples.md → docs/examples/azure/gitversion/execute.md

@@ -106,11 +106,13 @@ The Execute GitVersion task creates the following job-scoped variables and multi
 - commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
 - uncommittedChanges (since 5.5.0)
 - commitDate
+
 ---
 
 ## Execution Examples
 
 ### Example 1
+
 <details>
   <summary>Calculate the version for the build.</summary>
 
@@ -121,20 +123,23 @@ steps:
   - task: gitversion/[email protected]
     displayName: Determine Version
 ```
+
 </details>
 
 ### Example 2
 
 <details>
-  <summary>Calculate the version for the build using a config file with the default name **GitVersion.yml**.</summary>
+  <summary>Calculate the version for the build using a config file with the default name <b>GitVersion.yml</b>.</summary>
+  
 ```yaml
 steps:
   # gitversion/[email protected] task omitted for brevity.
 
-  - task: gitversion/[email protected]
+- task: gitversion/[email protected]
     displayName: Determine Version
     inputs:
       useConfigFile: true
+
 ```
 
 Example contents of **GitVersion.yml**:
@@ -147,12 +152,13 @@ branches:
   pull-request:
     tag: pr
 ```
+
 </details>
 
 ### Example 3
 
 <details>
-  <summary>Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.</summary>
+  <summary>Calculate the version for the build using a config file named <b>VersionConfig.yml</b> in the root of the working folder.</summary>
 
 ```yaml
 steps:
@@ -164,12 +170,13 @@ steps:
       useConfigFile: true
       configFilePath: 'VersionConfig.yml'
 ```
+
 </details>
 
 ### Example 4
 
 <details>
-  <summary>Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).</summary>
+  <summary>Show the effective configuration for GitVersion by running the <b>/showConfig</b> command (passed as an additional argument).</summary>
 
 ```yaml
 steps:
@@ -180,6 +187,7 @@ steps:
     inputs:
       additionalArguments: '/showConfig'
 ```
+
 </details>
 
 ### Example 5
@@ -197,6 +205,7 @@ steps:
       disableCache: true
       disableNormalization: true
 ```
+
 </details>
 
 ### Example 6
@@ -213,6 +222,7 @@ steps:
     inputs:
       updateAssemblyInfo: true
 ```
+
 </details>
 
 ### Example 7
@@ -231,17 +241,20 @@ steps:
         update-build-number=false
         next-version=2.0.1
 ```
+
 </details>
 
 ## Output usage
 
-The outputs can be accessed using the syntax `$(<id>.<outputName>)` or `$(<id>.GitVersion_<OutputName>)`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job.
+The outputs can be accessed using the syntax `$(<id>.<outputName>)` or `$(<id>.GitVersion_<OutputName>)`,
+where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job.
 
 The action also creates environment variables of the form `$(<outputName>)` or `$(GitVersion_<OutputName>)` for use by other steps in the same job.
 
 The multi-job output variables can be accessed across jobs and stages, in both conditions and variables.
 
-**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.** You can disable the default behavior by setting the `update-build-number` to `false` in the configuration file or by using the `overrideConfig` input.
+**GitVersion also automatically updates the pre-defined Build variable `Build.BuildNumber`.**
+You can disable the default behavior by setting the `update-build-number` to `false` in the configuration file or by using the `overrideConfig` input.
 
 ### Example 8
 
@@ -310,9 +323,11 @@ jobs:
         env:
           myvar_GitVersion_FullSemVer: $(version_step.GitVersion_FullSemVer)
 ```
+
 </details>
 
 ### Example 9
+
 <details>
   <summary>Calculate the version for the build and use the output in a subsequent job.</summary>
 
@@ -396,9 +411,11 @@ jobs:
         env:
           localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)
 ```
+
 </details>
 
 ### Example 10
+
 <details>
   <summary>Calculate the version for the build and use the output in a subsequent stage.</summary>
 
@@ -489,4 +506,5 @@ stages:
             env:
               localvar_GitVersion_FullSemVer: $(myvar_GitVersion_FullSemVer)
 ```
+
 </details>

docs/examples/azure/gitversion/index.md

@@ -6,8 +6,8 @@ Note: You need to run the Setup step before the Execute step, otherwise the Exec
 
 ## Setup GitVersion (gitversion/setup)
 
-- [Usage examples](setup/usage-examples.md)
+- [Usage examples](setup.md)
 
 ## Execute GitVersion (gitversion/execute)
 
-- [Usage examples](execute/usage-examples.md)
+- [Usage examples](execute.md)

docs/examples/azure/gitversion/setup/usage-examples.md → docs/examples/azure/gitversion/setup.md

@@ -2,7 +2,7 @@
 
 Find out how to use the **gitversion/setup** task using the examples below.
 
-> The examples use version _2.0.1_ of the GitVersion Execute task.  It is recommended to use the latest released version in your own workflows.
+> The examples use version _2.0.1_ of the GitVersion Setup task.  It is recommended to use the latest released version in your own workflows.
 
 ## Inputs
 

docs/examples/github/gitreleasemanager/setup.md

@@ -1,3 +1,9 @@
+# Setup GitReleaseManager Action (gitreleasemanager/setup) Usage Examples
+
+Find out how to use the **gitreleasemanager/setup** action using the examples below.
+
+> The examples use version _2.0.1_ of the GitReleaseManager Setup action.  It is recommended to use the latest released version in your own workflows.
+
 ## Inputs
 
 The Setup GitReleaseManager action accepts the following inputs:

docs/examples/github/gitversion/execute/usage-examples.md → docs/examples/github/gitversion/execute.md

@@ -108,6 +108,7 @@ The Execute GitVersion action creates the following outputs:
 - commitsSinceVersionSourcePadded (since 5.2.0, removed in 6.0.0)
 - uncommittedChanges (since 5.5.0)
 - commitDate
+
 ---
 
 ## Execution Examples
@@ -124,12 +125,13 @@ steps:
   - name: Determine Version
     uses: gittools/actions/gitversion/[email protected]
 ```
+
 </details>
 
 ### Example 2
 
 <details>
-  <summary>Calculate the version for the build using a config file with the default name **GitVersion.yml**.</summary>
+  <summary>Calculate the version for the build using a config file with the default name <b>GitVersion.yml</b>.</summary>
 
 ```yaml
 steps:
@@ -149,12 +151,13 @@ branches:
   pull-request:
     tag: pr
 ```
+
 </details>
 
 ### Example 3
 
 <details>
-  <summary>Calculate the version for the build using a config file named **VersionConfig.yml** in the root of the working folder.</summary>
+  <summary>Calculate the version for the build using a config file named <b>VersionConfig.yml</b> in the root of the working folder.</summary>
 
 ```yaml
 steps:
@@ -166,12 +169,13 @@ steps:
       useConfigFile: true
       configFilePath: VersionConfig.yml
 ```
+
 </details>
 
 ### Example 4
 
 <details>
-  <summary>Show the effective configuration for GitVersion by running the **/showConfig** command (passed as an additional argument).</summary>
+  <summary>Show the effective configuration for GitVersion by running the <b>/showConfig</b> command (passed as an additional argument).</summary>
 
 ```yaml
 steps:
@@ -183,6 +187,7 @@ steps:
       useConfigFile: true
       additionalArguments: '/showConfig'
 ```
+
 </details>
 
 ### Example 5
@@ -200,6 +205,7 @@ steps:
       disableCache: true
       disableNormalization: true
 ```
+
 </details>
 
 ### Example 6
@@ -216,6 +222,7 @@ steps:
     with:
       updateAssemblyInfo: true
 ```
+
 </details>
 
 ### Example 7
@@ -234,11 +241,13 @@ steps:
         update-build-number=false
         next-version=2.0.1
 ```
+
 </details>
 
 ## Output usage
 
-The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<outputName> }}` or `${{ steps.<id>.outputs.GitVersion_<OutputName> }}`, where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job.
+The outputs can be accessed using the syntax `${{ steps.<id>.outputs.<outputName> }}` or `${{ steps.<id>.outputs.GitVersion_<OutputName> }}`,
+where `<id>` is the ID assigned to the step that calls the action, by subsequent steps later in the same job.
 
 The action also creates environment variables of the form `${{ env.<outputName> }}` or `${{ env.GitVersion_<OutputName> }}` for use by other steps in the same job.
 
@@ -323,6 +332,7 @@ jobs:
         env:
           myvar_GitVersion_FullSemVer: ${{ steps.version_step.outputs.GitVersion_FullSemVer }}
 ```
+
 </details>
 
 ### Example 9
@@ -468,4 +478,5 @@ jobs:
         name: Use direct output from previous job (bash - outputs without prefix)
         shell: bash
 ```
+
 </details>

docs/examples/github/gitversion/index.md

@@ -6,8 +6,8 @@ Note: You need to run the Setup step before the Execute step, otherwise the Exec
 
 ## Setup GitVersion (gitversion/setup)
 
-- [Usage examples](setup/usage-examples.md)
+- [Usage examples](setup.md)
 
 ## Execute GitVersion (gitversion/execute)
 
-- [Usage examples](execute/usage-examples.md)
+- [Usage examples](execute.md)

docs/examples/github/gitversion/setup/usage-examples.md → docs/examples/github/gitversion/setup.md

@@ -2,7 +2,7 @@
 
 Find out how to use the **gitversion/setup** action using the examples below.
 
-> The examples use version _2.0.1_ of the GitVersion Execute action.  It is recommended to use the latest released version in your own workflows.
+> The examples use version _2.0.1_ of the GitVersion Setup action.  It is recommended to use the latest released version in your own workflows.
 
 ## Inputs
 

docs/versions.md

@@ -1,3 +1,5 @@
+# Versions and Compatibility
+
 | GitTools/actions | GitVersion       | GitReleaseManager  |
 |------------------|------------------|--------------------|
 | v1.x             | `>=5.2.0 <6.1.0` | `>=0.10.0 <0.18.0` |

envs/gitversion/execute/github.env

@@ -1,4 +1,4 @@
 GITHUB_WORKSPACE=.
 RUNNER_TEMP=./.test/temp
 RUNNER_TOOL_CACHE=./.test/tools
-GITVERSION_PATH=./.test/tools/GitVersion.Tool/6.10.0
+GITVERSION_PATH=./.test/tools/GitVersion.Tool/6.0.0