Anticipate and counter rogue blank line between header comment lines (introduced by Prettier)

[revelt]

As you know, Prettier cleans .md files. One of the actions it will make it will add a an empty line between each HTML comment line. Which, in our case, results in:

...
<!-- START doctoc generated TOC please keep comment here to allow auto update -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
...

Now, when doctoc is ran next time, it "doesn't see" the <!-- DON'T EDIT THIS SECTION line and it erroneously adds another one. We end up with:

## Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Each prettier+doctoc cycle will add one more: line break +<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> row.

Now, I achieved that Prettier would allow comment blocks, ie. <!-- prettier-ignore-start --> and <!-- prettier-ignore-end --> to prevent this from happening.

However, we should take steps to make doctoc more intelligent too and make it tolerate the blank lines between <!-- START doctoc and <!-- DON'T EDIT THIS SECTION. doctoc should not add duplicate line because of a single line break.

Do you think it's technically achievable?

[zackhsi]

Not to derail this issue, but in the vein of making doctoc more intelligent with respect to prettier, can we add an option to auto-generate the prettier-ignore-start and prettier-ignore-end comments?

[revelt]

@zackhsi good idea! It's interesting how much happened since I originally posted the above: GitHub sold us out, I moved all my libraries to BitBucket, got fed up with doctoc and coded up my own solution, which funnily is around 20 lines of code (it's within already existing but unreleased maintenance tool though, I used its parsing etc).

Speaking about doctoc, I know it's offtopic, but in theory it should not be used. The issue doctoc is trying to solve is bigger - it's the management of all other bits of readme: badges, title anchor generation, even updating h1 according to package.json. I wrote a library that comprehensively updates the readme's, without any config template files (unlike solutions like Jon Schlinkert's verb-cli) but haven't released it yet. It updates a lot of areas in readme, including TOC's. The main challenge is when you have 70 libraries on your hard drive and want to remove a badge from all of them. Or update the year in the footer. Or update a generic section like "how to contribute".

[markcellus]

got fed up with doctoc and coded up my own solution

@revelt sounds good. Where can I find it? is it on npm?

[revelt]

@mkay581 it's maintenance CLI, "lect", https://www.npmjs.com/package/lect — basically, premise is that readme itself is a carcass, as long as you stick to certain pattern, existing readme content slots can be updated/replaced with new ones. That's opposed to generating from scratch or Jon Schlinkert's https://github.com/verbose/verb-generate-readme — where special template is kept.

Now, TOC is only one of components and it was quick to gather h* titles and generate slugs for each. But Lect also updates many other areas, including some files outside readme — for example, npmrc, rollup config and updates package.json.

@mkay581 Feel free to inspect the lect's source, fork it, link local CLI and tweak it to your needs.