Generate TOC when exporting to HTML/PDF

[joe223]

A new feature：TOC

If there is a way to generator TOC automatically. Or, I just type [toc] in the first line，it will turn to A catalog and update while content is changing.

[joe223]

weird, I can not add a Label.

[Jocs]

@joe223 Do you mean to write HTML directly in Mark Text?

[joe223]

@Jocs just write [TOC].

example markdown content:

[toc]

# Chapter 1

## Chapter 1.1

## Chapter 1.2

# Chapter 2

finally, we got

<ul class="toc">
    <li><a href="#1">Chapter 1</a></li>
        <ul class="toc">
            <li><a href="#1-1">Chapter 1-1</a></li>
            <li><a href="#1-2">Chapter 1-2</a></li>
        </ul>
    <li><a href="#2">Chapter 2</a></li>
</ul>

# Chapter 1

## Chapter 1.1

## Chapter 1.2

# Chapter 2

[Jocs]

weird, I can not add a Label.
What's the meaning?

[joe223]

Only owner can set this.

[khaosdoctor]

I think there's an easier way to set a TOC within the text editor, like the VSCode extension does. Instead of adding a HTML string, just add more Markdown stuff inside some marked comments.

[gitfineon]

TOC is not defined in GFM, so I suggest to only add this as export option. Because how do you want to keep the table of contents up-to-date if there is already one inserted. You have to delete the old one and insert it again.

An export option for instance by replacing a special string like %TOC-H3% with the markdown representation of all headlines down to level 3 would be easier. A live representation is already there, so we don't need it twice.

But this is a non-critical feature, it does not make Mark Text more stable. Why is it selected for A more stable Mark Text . How about adding adding a Feature Wishlist project for the fun stuff.

[Jocs]

Why hasn't the TOC function been implemented?
Because I haven’t discovered the TOC in other places so far, I have not add it to Mark Text.
As you said, it does not belong to A more stable Mark Text .

[fxha]

@Jocs Why was this issue closed, it's still not implemented? I think it would be a good idea and would definitely prefer @gitfineon idea to generate the TOC when exporting a document to HTML/PDF and replace the [TOC] tag. Otherwise we should mark this as plugin.

TOC is not defined in GFM, so I suggest to only add this as export option. Because how do you want to keep the table of contents up-to-date if there is already one inserted. You have to delete the old one and insert it again.

An export option for instance by replacing a special string like %TOC-H3% with the markdown representation of all headlines down to level 3 would be easier. A live representation is already there, so we don't need it twice.

[Jocs]

@fxha Yes, it is not implemented, because TOC is not the syntax in the GFM standard, and we also implemented TOC navigation in the sidebar, so I thought it was not necessary to implement it. When exporting, I think we can add an option. Whether to export the TOC. This is a good idea, maybe add it later when optimizing the export feature.

[RoyiAvital]

It is important to allow the user to set the TOC Levels.

Something like TOC[2, 3, 4] which means only headers of Levels 2, 3 and 4 will enter the TOC.
The reason is usually # is used for title (Hence it shouldn't be in the TOC) and lower levels aren't needed.

[Dorian-DS]

@fxha Yes, it is not implemented, because TOC is not the syntax in the GFM standard, and we also implemented TOC navigation in the sidebar, so I thought it was not necessary to implement it. When exporting, I think we can add an option. Whether to export the TOC. This is a good idea, maybe add it later when optimizing the export feature.

The GFM should be considered minimal requirements, not maximum allowed. Additional features will not harm its use. There are other additional features in Marktext that are not part of GFM so I don't see why this can't be an editor feature. The sidebar navigation feels very much like an addon and removes the clean interface of seeing only the document itself how the author intended. Many documents are created using [TOC] which is supported on other editors.

[DutchPete]

The sidebar navigation feels very much like an addon and removes the clean interface of seeing only the document itself how the author intended.

I certainly do NOT agree with that, and it definitely does NOT remove the clean interface: the width can be set by the user. The sidebar navigation is a very useful feature and the devs have done a very good job implementing it.

What's more, for those who do not like the side bar or temporarily do not need it, they can turn it off in the menu, View, Toggle Side Bar.

[dakira]

@Jocs There doesn't need to be any extra syntax. Just ask if a TOC should be included on export. stackedit.io allows for this:

The result adds a navigational sidebar to the html like this:

[tweinreich]

@fxha Yes, it is not implemented, because TOC is not the syntax in the GFM standard, and we also implemented TOC navigation in the sidebar, so I thought it was not necessary to implement it. When exporting, I think we can add an option. Whether to export the TOC. This is a good idea, maybe add it later when optimizing the export feature.

The GFM should be considered minimal requirements, not maximum allowed. Additional features will not harm its use. There are other additional features in Marktext that are not part of GFM so I don't see why this can't be an editor feature. The sidebar navigation feels very much like an addon and removes the clean interface of seeing only the document itself how the author intended. Many documents are created using [TOC] which is supported on other editors.

I also hope it doesn't define the maximum that is possible. A [TOC] that is visible while editing, updates itself and also appears in an export would be really nice (I don't like the sidebar opened while writing as well).

Edit:
@DutchPete Yes they have done an awesome job and I don't think anyone wants to complain here.

I think it should be possible to discuss features in an open source community though.

Dorian-DS expresses a valid view in my opinion and I would as well prefer to have a [TOC]-element like e.g. Typora,

[kataras]

Hello,

This feature is not yet implemented? I am trying for hours to find a way to generate a TOC here...

[fxha]

I already have a basic implementation for this locally and can create a draft PR in the following days. It's not feature rich but works for navigating the file.

[CrystalRays]

Could Mark Text export pdf with the index?
What I mean is not the content table in document but the index info that could be recognized by the pdf viewer which will show it on the side bar.

[kouichi-c-nakamura]

Please give us a choice in Preference to enanle [toc] on Editor. It's simply a pain to go deal with a big markdown without [toc] jumps. Otherwise I may have to find another alternative...

[qds-soft]

GitLab has [TOC] implemented now. Would be really helpful to see it implemented in marktext, since I'm writeng quite extensive documentations for my projects.
I'd love to see it. Otherwise marktext is a really awesome editor.

[willzhang]

WE NEED IT ,THANKS

[SekoiaTree]

I dug through the code a bit; even though the implementation for exports is "there", it seems that the option is disabled. Is that intentional?

marktext/src/renderer/util/pdf.js

Line 93 in 2bb405a

const generateHtmlToc = (tocList, slugger, currentLevel, options) => {

returns nothing if tocList is empty, and that method is called by

marktext/src/renderer/util/pdf.js

Line 120 in 2bb405a

export const getHtmlToc = (toc, options = {}) => {

where the parameter toc is passed to generateHtmlToc.
This is then called by

marktext/src/renderer/components/editorWithTabs/editor.vue

Line 942 in 2bb405a

const htmlToc = getHtmlToc(this.editor.getTOC(), options)

, which passes this.editor.toc, which is created by

marktext/src/renderer/components/editorWithTabs/editor.vue

Line 552 in 2bb405a

const { container } = this.editor = new Muya(ele, options)

, which does not have any "toc" object. Therefore, the table of contents is never generated.

Several places also use

marktext/src/muya/lib/utils/exportHtml.js

Line 133 in 2bb405a

async renderHtml (toc) {

with no toc parameter passed, so maybe that's also the cause?

[2catycm]

Hello,

This feature is not yet implemented? I am trying for hours to find a way to generate a TOC too.

[allenzt]

Hi guys, thanks for your excellent work! Do you have any update?

[DutchPete]

@allenzt have a look at this: #1290 (comment)