Merge pull request #668 from wolf99/lint-markdown

Lint markdown

Author: ldennington

.github/workflows/lint-docs.yml

@@ -0,0 +1,19 @@
+name: "Lint documentation"
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main, linux ]
+  pull_request:
+    branches: [ main, linux ]
+
+jobs:
+  lint-markdown:
+    name: Lint markdown files
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@dcd71f646680f2efd8db4afa5ad64fdcba30e748
+
+      - uses: DavidAnson/markdownlint-cli2-action@744f913a124058ee903768d3adb92a4847e5d132
+        with:
+          globs: "**/*.md"

.markdownlint.jsonc

@@ -0,0 +1,6 @@
+// For information on writing markdownlint configuration see:
+//  https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig
+{
+    "MD013": false,  // Line length and line breaking convention not yet standardised across docs
+    "MD024": false   // The format for some files require repeated headings, e.g. "Example"
+}

CODE_OF_CONDUCT.md

@@ -67,10 +67,12 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+This Code of Conduct is adapted from the [Contributor Covenant][cc-homepage], version 1.4,
+available at [Contributor Covenant Code of Conduct][cc-coc].
 
-[homepage]: https://www.contributor-covenant.org
+For answers to common questions about this code of conduct, see the
+[Contributor Covenant FAQ][cc-faq]
 
-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+[cc-homepage]: https://www.contributor-covenant.org
+[cc-coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+[cc-faq]: https://www.contributor-covenant.org/faq

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-## Contributing
+# Contributing
 
-[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues 
+[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues
 [fork]: https://github.com/GitCredentialManager/git-credential-manager/fork
 [pr]: https://github.com/GitCredentialManager/git-credential-manager/compare
 [code-of-conduct]: CODE_OF_CONDUCT.md
@@ -13,24 +13,24 @@ Please note that this project is released with a [Contributor Code of Conduct][c
 
 ## Start with an issue
 
-0. Open an [issue][issue] to discuss the change you want to see.
+1. Open an [issue][issue] to discuss the change you want to see.
 This helps us coordinate and reduce duplication.
-0. Once we've had some discussion, you're ready to code!
+1. Once we've had some discussion, you're ready to code!
 
 ## Submitting a pull request
 
-0. [Fork][fork] and clone the repository
-0. Configure and install the dependencies: `dotnet restore`
-0. Make sure the tests pass on your machine: `dotnet test`
-0. Create a new branch: `git switch -c my-branch-name`
-0. Make your change, add tests, and make sure the tests still pass
-0. For UI updates, test your changes by executing a `dotnet run` in applicable UI-related project directories:
+1. [Fork][fork] and clone the repository
+1. Configure and install the dependencies: `dotnet restore`
+1. Make sure the tests pass on your machine: `dotnet test`
+1. Create a new branch: `git switch -c my-branch-name`
+1. Make your change, add tests, and make sure the tests still pass
+1. For UI updates, test your changes by executing a `dotnet run` in applicable UI-related project directories:
     - `Atlassian.Bitbucket.UI.Avalonia`
     - `GitHub.UI.Avalonia`
     - `Atlassian.Bitbucket.UI.Windows`
     - `GitHub.UI.Windows`
-0. Push to your fork and [submit a pull request][pr]
-0. Pat your self on the back and wait for your pull request to be reviewed and merged.
+1. Push to your fork and [submit a pull request][pr]
+1. Pat your self on the back and wait for your pull request to be reviewed and merged.
 
 Here are a few things you can do that will increase the likelihood of your pull request being accepted:
 

README.md

@@ -20,8 +20,8 @@ Git Credential Manager is currently available for Windows, macOS, and Linux\*. G
 
 Feature|Windows|macOS|Linux
 -|:-:|:-:|:-:
-Installer/uninstaller|✓|✓|✓
-Secure platform credential storage|&#10003;<br/>[(see more)](docs/credstores.md)|&#10003;<br/>[(see more)](docs/credstores.md)|&#10003;<br/>[(see more)](docs/credstores.md)
+Installer/uninstaller|&#10003;|&#10003;|&#10003;\*
+Secure platform credential storage|&#10003; [(see more)](docs/credstores.md)|&#10003; [(see more)](docs/credstores.md)|&#10003; [(see more)](docs/credstores.md)
 Multi-factor authentication support for Azure DevOps|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for GitHub|&#10003;|&#10003;|&#10003;
 Two-factor authentication support for Bitbucket|&#10003;|&#10003;|&#10003;
@@ -39,6 +39,7 @@ Proxy support|&#10003;|&#10003;|&#10003;
 - Debian/Ubuntu/Linux Mint
 - Fedora/CentOS/RHEL
 - Alpine
+
 ## Download and Install
 
 ### macOS Homebrew
@@ -87,7 +88,9 @@ sudo /usr/local/share/gcm-core/uninstall.sh
 ---
 
 <!-- this explicit anchor should stay stable so that external docs can link here -->
+<!-- markdownlint-disable-next-line no-inline-html -->
 <a name="linux-install-instructions"></a>
+
 ### Linux
 
 #### Experimental: install from source helper script
@@ -97,24 +100,24 @@ run the following:
 
 1. To ensure `curl` is installed:
 
-```shell
-curl --version
-```
+   ```shell
+   curl --version
+   ```
 
-If `curl` is not installed, please use your distribution's package manager
-to install it.
+   If `curl` is not installed, please use your distribution's package manager
+   to install it.
 
-0. To download and run the script:
+1. To download and run the script:
 
-```shell
-curl -LO https://raw.githubusercontent.com/GitCredentialManager/git-credential-manager/main/src/linux/Packaging.Linux/install-from-source.sh &&
-sh ./install-from-source.sh &&
-git-credential-manager-core configure
-```
+   ```shell
+   curl -LO https://raw.githubusercontent.com/GitCredentialManager/git-credential-manager/main/src/linux/Packaging.Linux/install-from-source.sh &&
+   sh ./install-from-source.sh &&
+   git-credential-manager-core configure
+   ```
 
-__Note:__ You will be prompted to enter your credentials so that the script
-can download GCM's dependencies using your distribution's package
-manager.
+   **Note:** You will be prompted to enter your credentials so that the script
+   can download GCM's dependencies using your distribution's package
+   manager.
 
 #### Ubuntu/Debian distributions
 
@@ -124,7 +127,8 @@ Download the latest [.deb package](https://github.com/GitCredentialManager/git-c
 sudo dpkg -i <path-to-package>
 git-credential-manager-core configure
 ```
-__Note:__ Although packages were previously offered on certain
+
+**Note:** Although packages were previously offered on certain
 [Microsoft Ubuntu package feeds](https://packages.microsoft.com/repos/),
 GCM no longer publishes to these repositories. Please install the
 Debian package using the above instructions instead.
@@ -249,7 +253,7 @@ See detailed information [here](https://aka.ms/gcm/httpproxy).
 
 ## Contributing
 
-This project welcomes contributions and suggestions.  
+This project welcomes contributions and suggestions.
 See the [contributing guide](CONTRIBUTING.md) to get started.
 
 This project follows [GitHub's Open Source Code of Conduct](CODE_OF_CONDUCT.md).

SECURITY.md

@@ -1,3 +1,5 @@
+# Security
+
 If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github)
 
 Thanks for helping make GitHub products safe for everyone.

docs/azrepos-users-and-tokens.md

@@ -64,7 +64,7 @@ credential. This may change in the future.
 
 Normally you won't need to worry about managing which user accounts Git
 Credential Manager is using as this is configured automatically when you first
-authenticate for a particular Azure DevOps organziation.
+authenticate for a particular Azure DevOps organization.
 
 In advanced scenarios (such as using multiple accounts) you can interact with
 and manage remembered user accounts using the 'azure-repos' provider command:
@@ -181,7 +181,7 @@ fabrikam:
 ```
 
 In the above example, the `~/myrepo` repository has a single Git remote named
-`origin` that points to the `contoso` Azure DevOps organziation. There is no
+`origin` that points to the `contoso` Azure DevOps organization. There is no
 user account specifically associated with the `origin` remote, so the global
 user account binding for `contoso` will be used (the global binding is
 inherited).

docs/bitbucket-development.md

@@ -63,20 +63,20 @@ Assuming the user successfully logins into Bitbucket and authorizes the GCM this
 
 The Access and Refresh Tokens will be stored against the username and the username/Access Token credentials returned to Git.
 
-# On-Premise Bitbucket
+## On-Premise Bitbucket
 
-On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, https://bitbucket.org. 
+On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, [bitbucket.org](https://bitbucket.org).
 
 As far as GCMC is concerned the main difference it doesn't support OAuth so only Basic Authentication is available.
 
 It is possible to test with Bitbucket Server by running it locally using the following command from the Atlassian SDK:
 
-	❯ atlas-run-standalone --product bitbucket
+    ❯ atlas-run-standalone --product bitbucket
 
-See https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/.
+See the developer documentation for [atlas-run-standalone](https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/).
 
 This will download and run a standalone instance of Bitbucket Server which can be accessed using the credentials `admin`/`admin` at
 
-	https://localhost:7990/bitbucket
+    https://localhost:7990/bitbucket
 
-Instructions on how to download and install the Atlassian SDK can be found here: https://developer.atlassian.com/server/framework/atlassian-sdk/
+Atlassian has [documentation](https://developer.atlassian.com/server/framework/atlassian-sdk/) on how to download and install their SDK.

docs/configuration.md

@@ -39,8 +39,8 @@ The following table summarizes the change in behavior and the mapping of older v
 Value(s)|Old meaning|New meaning
 -|-|-
 `auto`|Prompt if required – use cached credentials if possible|_(unchanged)_
-`never`,<br/>`false`| Never prompt – fail if interaction is required|_(unchanged)_
-`always`,<br/>`force`,<br/>`true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value)
+`never`, `false`| Never prompt – fail if interaction is required|_(unchanged)_
+`always`, `force`, `true`|Always prompt – don't use cached credentials|Prompt if required (same as the old `auto` value)
 
 #### Example
 
@@ -64,7 +64,7 @@ ID|Provider
 `azure-repos`|Azure Repos
 `github`|GitHub
 `bitbucket`|Bitbucket
-`gitlab`|GitLab<br/>_(supports OAuth in browser, personal access token and Basic Authentication)_
+`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_
 `generic`|Generic (any other provider not listed above)
 
 Automatic provider selection is based on the remote URL.
@@ -92,11 +92,11 @@ Select the host provider to use when authenticating by which authority is suppor
 Authority|Provider(s)
 -|-
 `auto` _(default)_|_\[automatic\]_
-`msa`, `microsoft`, `microsoftaccount`,<br/>`aad`, `azure`, `azuredirectory`,</br>`live`, `liveconnect`, `liveid`|Azure Repos<br/>_(supports Microsoft Authentication)_
-`github`|GitHub<br/>_(supports GitHub Authentication)_
-`bitbucket`|Bitbucket.org<br/>_(supports Basic Authentication and OAuth)_<br/>Bitbucket Server<br/>_(supports Basic Authentication)_
-`gitlab`|GitLab<br/>_(supports OAuth in browser, personal access token and Basic Authentication)_
-`basic`, `integrated`, `windows`, `kerberos`, `ntlm`,<br/>`tfs`, `sso`|Generic<br/>_(supports Basic and Windows Integrated Authentication)_
+`msa`, `microsoft`, `microsoftaccount`, `aad`, `azure`, `azuredirectory`, `live`, `liveconnect`, `liveid`|Azure Repos _(supports Microsoft Authentication)_
+`github`|GitHub _(supports GitHub Authentication)_
+`bitbucket`|Bitbucket.org _(supports Basic Authentication and OAuth)_, Bitbucket Server _(supports Basic Authentication)_
+`gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_
+`basic`, `integrated`, `windows`, `kerberos`, `ntlm`, `tfs`, `sso`|Generic _(supports Basic and Windows Integrated Authentication)_
 
 #### Example
 
@@ -196,7 +196,6 @@ git config --global credential.httpsProxy http://john.doe:password@proxy.contoso
 Override the available authentication modes presented during Bitbucket authentication.
 If this option is not set, then the available authentication modes will be automatically detected.
 
-
 **Note:** This setting only applies to Bitbucket.org, and not Server or DC instances.
 
 **Note:** This setting supports multiple values separated by commas.
@@ -227,7 +226,6 @@ Enabling this option will improve performance when using Oauth2 and interacting
 
 Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials everytime.
 
-
 Value|Refresh Credentials Before Returning
 -|-
 `true`, `1`, `yes`, `on` |Always
@@ -295,7 +293,6 @@ git config --global credential.gitLabAuthModes "browser"
 
 ---
 
-
 ### credential.namespace
 
 Use a custom namespace prefix for credentials read and written in the OS credential store.
@@ -323,7 +320,7 @@ Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset o
 
 Value|Credential Store|Platforms
 -|-|-
-_(unset)_|Windows: `wincredman`<br/>macOS: `keychain`<br/>Linux: _(none)_|-
+_(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|-
 `wincredman`|Windows Credential Manager (not available over SSH).|Windows
 `dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath](#credentialdpapistorepath)|Windows
 `keychain`|macOS Keychain.|macOS
@@ -332,7 +329,7 @@ _(unset)_|Windows: `wincredman`<br/>macOS: `keychain`<br/>Linux: _(none)_|-
 `cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).|Windows, macOS, Linux
 `plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`](#credentialplaintextstorepath).|Windows, macOS, Linux
 
-##### Example
+#### Example
 
 ```bash
 git config --global credential.credentialStore gpg
@@ -475,6 +472,7 @@ Credential: "git:https://github.com" (user = alice)
    https://github.com/contoso/widgets
    https://alice@github.com/contoso/widgets
 ```
+
 ```text
 Credential: "git:https://bob@github.com" (user = bob)
 
@@ -489,17 +487,20 @@ Credential: "git:https://github.com/foo/bar" (user = alice)
 
    https://github.com/foo/bar
 ```
+
 ```text
 Credential: "git:https://github.com/contoso/widgets" (user = alice)
 
    https://github.com/contoso/widgets
    https://alice@github.com/contoso/widgets
 ```
+
 ```text
 Credential: "git:https://bob@github.com/foo/bar" (user = bob)
 
    https://bob@github.com/foo/bar
 ```
+
 ```text
 Credential: "git:https://bob@github.com/example/myrepo" (user = bob)
 

docs/development.md

@@ -101,34 +101,35 @@ $ GCM_TRACE=1 git-credential-manager-core version
 If you want code coverage metrics these can be generated either from the command line:
 
 ```shell
-$ dotnet test --collect:"XPlat Code Coverage" --settings=./.code-coverage/coverlet.settings.xml
+dotnet test --collect:"XPlat Code Coverage" --settings=./.code-coverage/coverlet.settings.xml
 ```
 
 Or via the VSCode Terminal/Run Task:
 
-```
+```console
 test with coverage
 ```
 
 HTML reports can be generated using ReportGenerator, this should be installed during the build process, from the command line:
 
 ```shell
-$ dotnet ~/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage
+dotnet ~/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage
 ```
+
 or
 
 ```shell
-$ dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage
+dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage
 ```
 
 Or via VSCode Terminal/Run Task:
 
-```
+```console
 report coverage - nix
 ```
 
 or
 
-```
+```console
 report coverage - win
-```
+```