Add TOC for Bitbucket Server

[JoernBerkefeld]

What is the problem?

in bitbucket server you dont get the anker tags created for headlines which renders the TOC feature somewhat useless

How can I reproduce it?

Just try to use TOC and upload to bitbucket server (not the online version)

Is there any error message in the console?

no.

Solution

Add new command "Markdown All In One: Create Table of Contents (Bitbucket Server)". This command then needs to extend each headline like the following:

From:

### Getting Started

To:

<a name="getting-started"></a>
### Getting Started

[yzhang-gh]

Personally I don't think it is a proper Markdown feature. It is a workaround for Bitbucket which lacks the feature. I would suggest bringing this up to the Bitbucket team.

I will leave this issue open in case there are other users interested in this.

[JoernBerkefeld]

this has been brought up to the bitbucket team and there are numerous threads out there discussing it. fact of the matter is, bitbucket doesnt seem to be moving anywhere with it.

They added the custom token [TOC] in their SAAS version but the server version is left alone. Users are telling each other to use the described workaround.

I get that you want to keep the solution clean but then again, Bitbucket is one of the 2 biggest platforms using markdown - and in the enterprise world the bitbucket-server version is the way to go as far as I can tell from my client projects in the past 4 years.

[yzhang-gh]

bitbucket doesnt seem to be moving anywhere with it

That's too bad.

I get that you want to keep the solution clean

Exactly. Another way is you can have a separate extension "Bitbucket Markdown Heading Anchors" which only has this feature (to add proper <a> tags before headings).

(From my perspective, this is the first time Bitbucket is mentioned in this repository. So it can't be a good feature candidate at least for now)

[JoernBerkefeld]

Hi there, how about this: if there ARE <a> tags already above each header, could you include that their name-attributes are auto-updated when section numbering is toggled/updated?

[yzhang-gh]

Personally I would still suggest that someone make a standalone Bitbucket TOC extension. Its only feature is to generate proper <a> tags above headings as the TOC part can be generated by this extension.

Code that might be useful

Convert headings to name-attributes/ids https://github.com/yzhang-gh/vscode-markdown/blob/e88d6d5e148a0fa6ef19451867034d25c1753a29/src/util.ts#L161

Add/update section numbering https://github.com/yzhang-gh/vscode-markdown/blob/e88d6d5e148a0fa6ef19451867034d25c1753a29/src/toc.ts#L70

[JoernBerkefeld]

ok, i'll look into this. actually found a module this morning that might do this among other things... https://www.npmjs.com/package/markdown-it-toc-and-anchor-fork i'll try to understand how to wrap that into a vsc extension.

alternatively, what do you think about an optional callback in your code after toc insert/update and after toggle sectionNumbers?

[yzhang-gh]

ok, i'll look into this. actually found a module this morning that might do this among other things... https://www.npmjs.com/package/markdown-it-toc-and-anchor-fork

It seems to be a fork of https://github.com/medfreeman/markdown-it-toc-and-anchor, which may be a better choice.

By using above markdown-it plugin you are changing the Markdown rendering. As it doesn't change your Markdown source file, I'm not sure whether it works as you expect (on Bitbucket).

https://code.visualstudio.com/api/extension-guides/markdown-extension#adding-support-for-new-syntax-with-markdownit-plugins

alternatively, what do you think about an optional callback in your code after toc insert/update and after toggle sectionNumbers?

I'm not quite sure how to do it. IMO, TOC and <a> tags are both based on the headings and meanwhile independent. It should be enough to execute your code after the file save event (because file is always in a unsaved state after "insert/update TOC" and "add/update/remove section numbers" commands.)

[JoernBerkefeld]

I suppose the idea would be to deactivate all other linting & style correction and limit the new thing to anchor tags. Using a lib for that might make sense to ensure the same format is used.

BTW: in my current main project (not public) I've switched over to prettier+markdownlint. Reason being that I was using both before anyways, only that I didnt use prettier for style corrections in markdown yet. However, it seemed like a good move to keep this central. Your plugin is kept for all other things, including TOC.

[yzhang-gh]

Just to let all you know that there is a new slugify mode bitbucket-cloud now (not Bitbucket Server as it doesn't generate heading ids at all).

#861