Proposal: Implement the same API as other toc generators

[sdwolfz]

I would like to see the same API implemented by these two projects supported here as well:

https://github.com/nok/markdown-toc https://github.com/AlanWalk/Markdown-TOC

The idea is to be able to generate an identical TOC from multiple code editors (Atom, VSCode, Emacs). This would allow TOC refreshes to be automatically done from any compatible editor without messing up the diff.

Generally this would mean having the TOC between the generic html comments:

<!-- TOC -->
<!-- /TOC -->

And controlling the behaviour through attributes:

<!-- TOC withLinks:1 updateOnSave:1 -->
<!-- /TOC -->

Those two projects seem to adhere to these settings already. I am willing to put in the effort to implement this as I already am familiar with the functionality, but I don't make any promise on when this will be delivered.

Let me know what you think!

/cc @nok @AlanWalk in case you have anything extra to add.

[ardumont]

Let me know what you think!

Interesting!

I just think of the case of people already using the tool needs their buffer to migrate. So from the top of my head, i see 2 possibilities, either:

• migrate silently, markdown-toc-generate detects and adapt accordinly the new delimiter comment.
• do not migrate and let the user decide to migrate or not (adding a new interactive command markdown-toc-migrate), keeping the actual behavior if not migrated, using the new one you propose if not migrated (seems not that nice though).

Well, feel free to choose then ;)

... but I don't make any promise on when this will be delivered.

Sure, to simplify and ease the time to market ;), you could split this into multiple PRs:

• 1 would introduce the new comment (i used my complicated thing at the time to avoid clash, maybe that was dumb).

• another one would introduce the parametric comment (hard part maybe?)...

But that's from the top of my head ;)

Cheers,

[sdwolfz]

The only problem I see is that currently settings are handled trough global settings in the emacs config, compared to local settings in the <!-- TOC --> comment.

I'll open a WIP PR when I start and document all the problems I hit there. This will end up being a breaking change, so it will need to be released as a major version increase, I'll see how easy it is to maintain compatibility.

[ardumont]

I checked the start of the code again, it's been a while since i looked, here are the customs to setup the start/end tags:

(defcustom markdown-toc-header-toc-start
  "<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->"
  "Beginning delimiter comment."
  :group 'markdown-toc)

(defcustom markdown-toc-header-toc-title
  "**Table of Contents**"
  "Title comment on TOC header."
  :group 'markdown-toc)

(defcustom markdown-toc-header-toc-end
  "<!-- markdown-toc end -->"
  "Ending delimiter comment."
  :group 'markdown-toc)

It's defcustom already so you might be able to check you can actually have what you want already (well the 1. part i mentioned at least ;) by changing to something like:

(custom-set-variables '(markdown-toc-header-toc-start "<!-- TOC -->")
                      '(markdown-toc-header-toc-title "")
                      '(markdown-toc-header-toc-end "<!-- TOC -->"))

Cheers,

[sdwolfz]

Don't forget about markdown-toc-user-toc-structure-manipulation-fn. I'll also need to analyze the other repos to find a list of common parameters, find their defaults and implement them. Anyway, I'll get back to you with mode details when I actually start working on it. Right now I only have a vague idea on what I will change and I might be wrong on my assumptions.

Side note, it would be nice if vim/sublime/intellij had similar functionality implemented. I might put it as a side goal to get all major editors in line with this approach. Starting off with atom and vscode since they were they already have some compatibility.

[sdwolfz]

Closing this as I'm no longer interested in the feature, and I won't be able to work on it.