feat: add markdownlint #538
Conversation
|
it's "green" because of |
|
markdownlint does now run without |
smortex
left a comment
smortex
left a comment
There was a problem hiding this comment.
Nice! I am just worried by the configuration file. I have no experience with this tool, but on the check pages I see "aliases" which makes me think that maybe we can have something easier to digest (example line_length rather than MD013)?
binford2k
left a comment
binford2k
left a comment
There was a problem hiding this comment.
I'll be honest, in general I don't really see the point of markdownlint, especially when its recommendations make the source doc harder to read -- the express purpose of markdown in the first place. Or when it requests pointless changes like insisting on _underscore emphasis_ instead of *asterisks* or requiring shell instead of bash. All that does is increase friction of getting people to write docs and posts in the first place.
I didn't do a thorough proofread, just highlighted instances of unhelpful changes.
|
|
||
| {write a guide on how to deploy, configure, and use this architecture} | ||
|
|
||
|
|
There was a problem hiding this comment.
These extra spaces between headlines are incredibly helpful when reading the source doc. Please disable this check.
| Puppetboard --- OpenVoxDB | ||
| OpenVoxServer --- Agent1("Agent 1") & Agent2("Agent 2") & Agent_n("Agent n") | ||
|
|
||
| click Foreman "https://www.theforeman.org/" |
There was a problem hiding this comment.
this code is a mermaid diagram
| We recommend managing each of these components with the supported module. | ||
|
|
||
| * OpenVoxDB | ||
| * [puppetlabs/puppetdb](https://forge.puppet.com/puppetlabs/puppetdb) |
There was a problem hiding this comment.
It doesn't hurt to have deeper indentation steps and it often makes it easier to read.
| --- | ||
|
|
||
| - [Running the tests in a local ruby environment](#running-the-tests-in-a-local-ruby-environment) | ||
| * [Installing dependencies](#installing-dependencies) |
There was a problem hiding this comment.
it's entirely valid and useful to use different markers to indicate list depth.
| Check out the following page if you want to add a test suite to your module or want | ||
| to learn more about the Vox Pupuli test helpers: | ||
|
|
||
| * [voxpupuli-test](https://github.com/voxpupuli/voxpupuli-test) for unit testing |
There was a problem hiding this comment.
the intent of this list is perfectly clear, even if another part of the doc used a different marker
| ``` | ||
|
|
||
| ## Contribute?! | ||
| ## Contribute? |
There was a problem hiding this comment.
this is a stylistic choice and it's perfectly valid to express excitement in this way.
| Now you can install the changelog generator: | ||
|
|
||
| ```bash | ||
| ```shell |
| *Please note that in order to execute this rake task you must be in the __Collaborators__ group on GitHub for the module in question.* | ||
|
|
||
| *Please also note that the task requires a configured gpg or ssh key in your local git settings to sign the git tag* | ||
| * _Please note that in order to execute this rake task you must be in the __Collaborators__ group on GitHub for the module in question._ |
There was a problem hiding this comment.
this changes the rendering of the doc for no reason.
| [Martin](https://github.com/tuxmea) was the first to submit a nomination, and as promised Puppet will be sending him a brand spankin' fresh hoodie as soon as we've got the new design finalized. | ||
|
|
||
| ## Let's get to it and meet your new PMC members! | ||
| ## Let's get to it and meet your new PMC members |
There was a problem hiding this comment.
expressing excitement is perfectly valid
4 participants
No description provided.