feat(toc): use markdown-toc directly to update inline
#43
Conversation
* https://github.com/jonschlinkert/markdown-toc - Generate a markdown TOC (table of contents) for any markdown files.
| # Update Tables of Content in the relevant `.md` files | ||
| - npm install markdown-toc -D | ||
| - markdown-toc -i CONTRIBUTING.md | ||
| # - markdown-toc -i README.md |
There was a problem hiding this comment.
I've put this in here since using README.md is common across our repos. That also begs the question -- should we modify the .rst to .md in this repo, too?
There was a problem hiding this comment.
If you make me answer quickly, I'd say that md is more common in github projects, but sincerely don't know. I'm OK with both of them (use rst mostly when I have to write pdfs parsing them with rst2pdf), but I'm no strongly biased for one over the other.
If you know there's a recommended one for github projects, I'd say let's use that one?
There was a problem hiding this comment.
I'm not endorsing any particular format, I have to accommodate for three (I prefer asciidoctor myself). Looking at the wider picture, Markdown is the most common, making the barrier of entry lower (i.e. for contributions). The solutions we're currently using for automation usually work best for, or are limited to, Markdown files. Then it simply becomes an issue of consistency of formats across the repo.
There was a problem hiding this comment.
There is comparison of RST and MD here: http://hyperpolyglot.org/lightweight-markup
I have used both, have preferred rst when I want to include media/links in the markup.
There was a problem hiding this comment.
@noelmcloughlin Thanks for that. None of us is doubting which is the superior format. This is really about which is the most accessible, both for other contributors as well as the automated solutions that we're introducing. From that angle, Markdown can't be denied. We're using it throughout GitHub and everywhere else, wherever heavy-lifting isn't required. And the docs stored in the main repo are hardly going to be that. If we ever get around to producing some serious documentation or even populating the formulas' wikis, the other formats come into their own.
| <!-- toc --> | ||
| <!-- tocstop --> | ||
| </td></tr></table> | ||
|
|
There was a problem hiding this comment.
I toyed with keeping this simpler (without the table) but found that it is much nicer with it. This would be a standard copy-paste block that will then be filled automatically by markdown-toc during the release phase.
| @@ -19,7 +27,7 @@ type(scope): subject | |||
| Besides the version bump, the changelog and release notes are formatted accordingly. | |||
| So based on the example above: | |||
|
|
|||
| > ### Documentation | |||
| > <h3>Documentation</h3> | |||
| > | |||
There was a problem hiding this comment.
This is the workaround when quoting text with headers. Really, markdown-toc should handle this but it would mean maintaining our own fork.
|
Thanks for taking the time to review, @javierbertoli. |
|
🎉 This PR is included in version 0.6.0 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Our Markdown files are quite lengthy, with content still to be added. Having a TOC is invaluable but manual maintenance is a pain. Using the available package linked above, the process of maintaining the TOC across all relevant files is automated during the Travis
semantic-releaserun.