Markdownlint
•
0 likes•209 views
Markdownlint is a linter tool that checks Markdown files for formatting errors and inconsistencies. It helps ensure correctness, uniformity, and consistency across large documentation sets or multiple documents. There are Ruby and Node.js implementations of Markdownlint that define rules for formatting and can be integrated into text editors, command line, and continuous integration tools like Travis CI to catch basic Markdown issues before committing changes.
Markdownlint
- 1. Markdownlint a snap-snazzy introduction to linting your Markdown by jonasbn for CopenhagenJS February 2019 !1
- 2. Who me? Product Manager with DK Hostmaster A/S coming from a developer background Writing A LOT of material in Markdown ݺߣs are available: / jonasbn !2
- 3. What is Markdown? Markdown is a lightweight markup language with plain text formatting syntax for translation into other output formats It was invented by John Gruber and Aaron Schwartz back in 2004 Check: https://en.wikipedia.org/wiki/Markdown There are plenty of flavours like GFM (GitHub Flavoured Markdown) and the standardisation CommonMark etc. !3
- 4. What is CommonMark? CommonMark is a attempt at a standardisation of Markdown It was initiated by Jeff Atwood and John McFarlane among others back in 2012 Again check: https://en.wikipedia.org/wiki/Markdown Do also check: https://commonmark.org/ https://github.com/CommonMark/CommonMark !4
- 5. example !5
- 6. What is lint-ing? - and why? Lint is cruft and linting is the proces of removing unwanted stuff Meaning that for anything where we can talk about order, uniformity, rules and consistency it is possible to identify lint And hopefully identification will lead to removal or other sort of addressing !6
- 8. What is lint-ing? - and why? • In general • Linters can take care of the boring and obvious stuff and leave the more subtle and complex issues to the humans • Meaning you get to focus on the content or code, structure, potential bugs or security issues etc. which linters cannot catch • So do linting before you do code/peer review
- 9. What is Markdownlint? Ruby Implementation: https://github.com/markdownlint Node Implementations: https://github.com/DavidAnson/markdownlint https://github.com/igorshubovych/markdownlint-cli All rules are identified by a name: MDXXX and an human- readable alias !9
- 10. Why Markdownlint? Markdownlint allow us to ensure Correctness and uniformity for our huge documents or across several documents It allows us to specify rules or exceptions on how we want our structure or basic formatting to be shaped And it can catch basic Markdown bugs, before you commit !10
- 11. example !11
- 12. Rules and Exceptions Markdownlint (Ruby) implements 38 rules Markdownlint (Node) implements 44 rules So the two implementations are not completely aligned The two implementations differ in overall configuration method, but implement the same concept of enabling and disabling specific rules I cannot state that the two implementations implement completely the same configuration parameters for specific rules !12
- 13. Toolchains and Integrations Sublime Text Visual Studio Code Or just plain command line Or you can write your own integration since both the Ruby and Node implementations are founded in libraries !13
- 14. example !14
- 15. Bonus Material Integration with Travis CI (.travis.yml) !15
- 17. example !17
- 18. Recap Markdown is good, easy to use and widely available, you can write documentation quite easily using your favorite tools Linters helps us avoid common mistakes and ensures wide uniformity and consistency and can do the heavy lifting prior to a code/peer review Markdownlint is a good extension to your Markdown toolbox, easy to use, configurable, widely available, it helps us avoid common mistakes and ensures wide uniformity and consistency Markdownlint can be used with most tools like editors and CI/ CD and of course the command line !18