Lint markdown #668

wolf99 · 2022-04-15T21:18:06Z

Making this change with multiple commits to make it easier to revert any parts that people don't like 🙂
I have some questions before making later commits.
In a final commit, I have introduced a GitHub workflow that adds a markdown lint step so that the linting can be easily maintained.

This PR will probably cause merge conflicts with #237, #551, and #607

wolf99 · 2022-04-15T22:00:17Z

README.md

-<!-- this explicit anchor should stay stable so that external docs can link here -->
-<a name="linux-install-instructions"></a>


Is this actually linked from external docs? (@vtbassmatt maybe?)

If so, is there a commitment not to break this specific link for some reason?

Docs (anywhere) can link to headings in markdown using the url#heading syntax, as in docs/wsl.md in this commit. There isn't usually any need to add additional, explicit anchors for markdown headings. There are linting rules against: HTML in markdown; having content in lines immediately before or after a heading.

It's linked from at least the GitHub docs on the topic (you may have to click over to the Linux tab) and possibly other vendors as well.

Thanks! I'll experiment with a few options for solving this in a lint-friendly way then.

Are these docs rendered only on GitHub or also in other locations that I should test the results against?

If you mean the docs in this repo, no – we don't render them anyplace else.

Turns out GitHub Flavored Markdown does not support custom heading links in any form.
So I've ended up simply adding an "ignore" for the specific linting rule for this anchor (in 8cf643a)

wolf99 · 2022-04-16T10:09:00Z

Two more general issues remain:

Both docs/environment.md and docs/configuration.md contain many multiple headings with the same content.

The first contains many headings of:
- "Example"
- "Windows"
- "macOS/Linux"
While the latter contains many headings of "Example"

There are some options to resolve this:
1. Restructure these documents so as to avoid this heading pattern
2. Add configuration to markdown lint CI to ignore these forever (this option is currently implemented in the workflow introduced in this PR)
Which is preferred?
There appears to not be a uniform approach to line length. It looks like some files break on a given character column length (something < 80), while others break at the end of sentence.

My own opinion is that the latter is better for readability and more in the spirit of markdown itself, but as with most things in programming it is more important that any approach be uniform and I am happy to implement any approach that is preferred.

The linting workflow introduced in this PR is currently configured to ignore line length.

Is there a preference?

ldennington

Thanks for working to make our docs better! ✏️

ldennington · 2022-04-18T17:07:32Z

CONTRIBUTING.md

 This helps us coordinate and reduce duplication.
-0. Once we've had some discussion, you're ready to code!
+2. Once we've had some discussion, you're ready to code!


Are we able to add an exception instead of making this change? We tend to use the 1/0 formatting on purpose, as it makes it easier to add new items in lists (i.e. we don't have to go change all the other numbers when we put something new in the middle).

I've always felt this reasoning was overrated; if someone is making changes to a document anyway, then it's not hard to change a handful of list numbers as well (for relatively short lists). It's can also get a little confusing when working with sub-lists and sub-sub lists, when they are all the same number.

The benefit of proper numbering is that the markdown provides the same information in raw form as in rendered form.

Nevertheless, I have updated the docs to use the form of repeated 1., as this form is accepted by the linter (repeated 0. also works but means that lists start at 0 rather than 1), in commit 1b24d82

ldennington · 2022-04-18T17:18:12Z

CODE_OF_CONDUCT.md


-For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+[homepage]: https://www.contributor-covenant.org


Nit: maybe cc-homepage or cc_homepage?

Good call!
Added in 7f3f110

ldennington · 2022-04-18T17:19:42Z

docs/bitbucket-development.md

@@ -65,18 +65,18 @@ The Access and Refresh Tokens will be stored against the username and the userna

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


Should we have short names for links in this document similar to those added in CODE_OF_CONDUCT.md?

Yes! 🙂
I will work on doing this for all markdown files.

At the same time I will replace aka.ms links that refer to other docs within this repo with relative links, so as to:

Remove dependency on MS short link service

Allow links to work offline.

Please let me know if this latter part is not wanted.

I am ok with the latter part, but I think @mjcheetham may want to weigh in on this.

ldennington · 2022-04-18T17:20:34Z

docs/gitlab.md

-1. No support for OAuth device authorization (necessary for machines without web browser) https://gitlab.com/gitlab-org/gitlab/-/issues/332682
-2. Only domains with prefix `gitlab.` are recognised as GitLab remotes https://gitlab.com/gitlab-org/gitlab/-/issues/349464
-3. Username/password authentication is suggested even if disabled on server https://gitlab.com/gitlab-org/gitlab/-/issues/349463
+1. No support for OAuth device authorization (necessary for machines without web browser): [GitLab issue 332682](https://gitlab.com/gitlab-org/gitlab/-/issues/332682)


Should we have short names for the links in this document similar to those added in CODE_OF_CONDUCT.md?

ldennington · 2022-04-18T17:36:06Z

Two more general issues remain:

Both docs/environment.md and docs/configuration.md contain many multiple headings with the same content.
The first contains many headings of:

"Example"

"Windows"

"macOS/Linux"

While the latter contains many headings of "Example"
There are some options to resolve this:

Restructure these documents so as to avoid this heading pattern

Add configuration to markdown lint CI to ignore these forever (this option is currently implemented in the workflow introduced in this PR)

Which is preferred?

I think it is fine to ignore in this case. I don't think having multiple of the same heading in one file is a huge deal.

There appears to not be a uniform approach to line length. It looks like some files break on a given character column length (something < 80), while others break at the end of sentence.
My own opinion is that the latter is better for readability and more in the spirit of markdown itself, but as with most things in programming it is more important that any approach be uniform and I am happy to implement any approach that is preferred.
The linting workflow introduced in this PR is currently configured to ignore line length.
Is there a preference?

My preference would be to break on a character column link. If we decide to do this, I'm good with doing < 80.

wolf99 · 2022-04-23T09:44:10Z

Thank you for the review @ldennington !

There are two things remaining in progress

Line lengths
Reference style links

I will continue to work on these, but perhaps this can be merged as it currently is, with those as separate PRs?

The reason being it is already a large change and I am aware of other PRs that also have doc changes, I wouldn't like this PR to block these changes cause too many merge conflicts to those or vice-versa. Both of the above changes will be a lot of change across many files.

wolf99 · 2022-04-23T18:35:18Z

Rebased and fixed merge conflicts

ldennington · 2022-04-25T21:57:17Z

Thank you for the review @ldennington !

There are two things remaining in progress

Line lengths

Reference style links

I will continue to work on these, but perhaps this can be merged as it currently is, with those as separate PRs?

The reason being it is already a large change and I am aware of other PRs that also have doc changes, I wouldn't like this PR to block these changes cause too many merge conflicts to those or vice-versa. Both of the above changes will be a lot of change across many files.

I'm fine with this!

Thank you for the review @ldennington !

There are two things remaining in progress

Line lengths

Reference style links

I will continue to work on these, but perhaps this can be merged as it currently is, with those as separate PRs?

The reason being it is already a large change and I am aware of other PRs that also have doc changes, I wouldn't like this PR to block these changes cause too many merge conflicts to those or vice-versa. Both of the above changes will be a lot of change across many files.

Sounds great! I just did another review, and it all looks good. I will proceed with the merge.

wolf99 commented Apr 15, 2022

View reviewed changes

wolf99 marked this pull request as draft April 15, 2022 22:10

wolf99 marked this pull request as ready for review April 16, 2022 16:53

ldennington approved these changes Apr 18, 2022

View reviewed changes

wolf99 mentioned this pull request Apr 19, 2022

Add dependabot #674

Merged

wolf99 added 11 commits April 23, 2022 19:25

Fix md lint errors that do not alter content

dbb8e41

Fix bare URLs

3f42fce

Fix inline HTML

e78add7

Remove spaces inside code-span elements

9f3b269

Fix multiple top-level headings

637bf1a

Fix console commands without output

1f21050

Add markdown linting to workflows

a319c6a

Fix spellings

2379ac1

Ignore lint for anchor for Linux install instructions

43ee90b

Adjust list numbering format

b48ad39

Improve link reference IDs

192b5b7

wolf99 force-pushed the lint-markdown branch from 7f3f110 to 192b5b7 Compare April 23, 2022 18:34

Fix new list lint issue

5b763c0

ldennington merged commit 86714ff into git-ecosystem:main Apr 25, 2022

wolf99 deleted the lint-markdown branch April 26, 2022 09:26

wolf99 mentioned this pull request Apr 28, 2022

Switch to reference style links #680

Merged

ldennington mentioned this pull request Jun 15, 2022

Release 2.0.779 #746

Merged

wolf99 mentioned this pull request Sep 9, 2022

Unify line length across docs #862

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Lint markdown #668

Lint markdown #668

wolf99 commented Apr 15, 2022 •

edited

Loading

wolf99 Apr 15, 2022 •

edited

Loading

vtbassmatt Apr 18, 2022

wolf99 Apr 18, 2022 •

edited

Loading

vtbassmatt Apr 18, 2022

wolf99 Apr 22, 2022

wolf99 commented Apr 16, 2022 •

edited

Loading

ldennington left a comment

ldennington Apr 18, 2022

wolf99 Apr 23, 2022

ldennington Apr 25, 2022

ldennington Apr 18, 2022

wolf99 Apr 23, 2022

ldennington Apr 18, 2022

wolf99 Apr 23, 2022

ldennington Apr 25, 2022

ldennington Apr 18, 2022

ldennington commented Apr 18, 2022 •

edited

Loading

wolf99 commented Apr 23, 2022 •

edited

Loading

wolf99 commented Apr 23, 2022

ldennington commented Apr 25, 2022

		<!-- this explicit anchor should stay stable so that external docs can link here -->
		<a name="linux-install-instructions"></a>

Lint markdown #668

Lint markdown #668

Conversation

wolf99 commented Apr 15, 2022 • edited Loading

wolf99 Apr 15, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wolf99 Apr 18, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wolf99 commented Apr 16, 2022 • edited Loading

ldennington left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldennington commented Apr 18, 2022 • edited Loading

wolf99 commented Apr 23, 2022 • edited Loading

wolf99 commented Apr 23, 2022

ldennington commented Apr 25, 2022

wolf99 commented Apr 15, 2022 •

edited

Loading

wolf99 Apr 15, 2022 •

edited

Loading

wolf99 Apr 18, 2022 •

edited

Loading

wolf99 commented Apr 16, 2022 •

edited

Loading

ldennington commented Apr 18, 2022 •

edited

Loading

wolf99 commented Apr 23, 2022 •

edited

Loading