Add support for a table of contents

[kura]

I would like to be able to insert a table of contents in some pages, ideally with some macro like [toc]. Would this be a possible future addition.

[Linbreux]

Yes I think this would be simple to implement, I'll look into it within a few days/weeks

[Linbreux]

Hi @kura
I tried building a small Macro system. Could you give it a try and let me know if this is what you had in mind?
You can check it out at https://github.com/Linbreux/wikmd/tree/macro_support

[kura]

@Linbreux sure thing, I'll give it a whirl this afternoon and report back.

[kura]

Ok, I have a couple of notes:

1. [[TOC 1]] seems kind of pointless in it's currently form. Given you really should only have a single <h1> element in a page and that already exists in the Wiki (the name of the page) I think [[TOC 1]] should only encompass <h2> elements, [[TOC 2]] would be then be <h2> and <h3>, [[TOC 3]] would then be <h2>, <h3>, and <h4> etc etc. But... I guess there may be people who do use multiple <h1> tags since the content is just freeform MD so maybe it's better to leave it as it is...
2. I think the CSS could do with a little bit of work
   • There is a bit too much padding between list items.
   • I personally feel like the first level of links should be aligned to the same left margin as the headers and content.
   • I think maybe some styling of the links to show they are links would be an idea, removing the bolding and making them underlined seems like a solid solution to me.
   • Would this ToC not be easier to implement and style as an unordered list <ul> with list items <li> rather than each individual item being a paragraph <p>?
     • On that note, I think some of the generation is a bit wonky, each item in the ToC has an id with no value <p id>.
3. Can you add some optional arguments to the macro, like an optional title replacement? i.e. the current title is Table of content, I would like to be able to override that to just say Contents.
4. I'm sure you won't forget this but it's also worth noting BeautifulSoup4 is not in requirements.txt

All I did to make these tweaks was;

• Find all items in the ToC and remove 20px from the left margin, i.e. 20px -> 0px, 40px -> 20px. I am honestly not sure the best way to do this if you allow multiple <h1> tags since it'll mean documents like mine that only have h2 and above will always have additional padding that messes the list up... Maybe you could include a default empty custom.css file that people like me and either edit when running locally or mount over when using the container?
• Change the <p> styling for margin-bottom from 1rem to 5px. I wouldn't advise just doing this though since it screws up paragraph spacing in the document, hence why I mentioned above just doing it as an unordered list for easier styling
• Remove font-weight: bold
• Add text-decoration: underline

How it currently looks	My tweaks

[Linbreux]

hi @kura

Thanks for the fast and detailed review and tests, really appreciate it!

But... I guess there may be people who do use multiple <h1> tags since the content is just freeform MD so maybe it's better to leave it as it is...

Yes I also think h1 should be in the TOC!

2. I think the CSS could do with a little bit of work

Yes completely agree! I just made this really quick to see if this was something that would work. uland il would be a better option!

3. Can you add some optional arguments to the macro, like an optional title replacement? i.e. the current title is Table of content, I would like to be able to override that to just say Contents.

This should be possible, maybe in the config file, or should it be document specific?

4. I'm sure you won't forget this but it's also worth noting BeautifulSoup4 is not in requirements.txt

Yes I'm aware of this, but thanks for noting ;)

All I did to make these tweaks was;

• Find all items in the ToC and remove 20px from the left margin, i.e. 20px -> 0px, 40px -> 20px. I am honestly not sure the best way to do this if you allow multiple <h1> tags since it'll mean documents like mine that only have h2 and above will always have additional padding that messes the list up... Maybe you could include a default empty custom.css file that people like me and either edit when running locally or mount over when using the container?

Yes that would be possible, maybe an option for title_as_h1= true

• Change the <p> styling for margin-bottom from 1rem to 5px. I wouldn't advise just doing this though since it screws up paragraph spacing in the document, hence why I mentioned above just doing it as an unordered list for easier styling
• Remove font-weight: bold
• Add text-decoration: underline

I will change it to an unordered list. The margin at the bottom is indeed way to much. I don't know if I like the underline text decoration, I think this is a little outdated. This could also be available in a custom css file.

[kura]

@Linbreux

Thanks for the fast and detailed review and tests, really appreciate it!

No problem. I've been looking forward to this feature a for while, some of my documents are pretty large to try and scroll through without a ToC.

This should be possible, maybe in the config file, or should it be document specific?

I can't think of a reason I'd ever want it to be different in different documents so in the config file seems very reasonable to me.

Yes that would be possible, maybe an option for title_as_h1= true

Also seems like a very reasonable solution to me.

I will change it to an unordered list. The margin at the bottom is indeed way to much. I don't know if I like the underline text decoration, I think this is a little outdated. This could also be available in a custom css file.

That's fair, although all other links in the wiki pages use the old school link styling of being blue and underlined. :D

[Linbreux]

That's fair, although all other links in the wiki pages use the old school link styling of being blue and underlined.

^^ haha yes, that's also something I need to change :)

[kura]

@Linbreux just FYI I've started poking the ToC branch. I've managed to make it a little bit faster and am working on switching it over to nested unordered lists.

[Linbreux]

@kura Alright! My work was more like a draft to see if it was possible to create a full macro system. Optimization was not yet on my radar, so I'm glad you improved it already!

[kura]

@Linbreux that's fair. I gained most of the performance benefits by switching the macro detection and parsing out to a single compiled REGEX and changed it to only run one of the macro classes if a matching macro exists.

I tried to get pandoc to do the ToC generation too since --toc and --toc-depth are options but couldn't get it to generated a ToC. :/

[Linbreux]

I tried to get pandoc to do the ToC generation too since --toc and --toc-depth are options but couldn't get it to generated a ToC. :/

@kura I also tried that once in the passed, but didn't got it to work. I'm also curious if it's easy to generate an indented unordered list with bs4 ;)

[kura]

@Linbreux commented on 7 Sept 2022, 21:39 UTC:

I'm also curious if it's easy to generate an indented unordered list with bs4 ;)

My approach to this was iterators, basically iterate until the header level changes, if the level increases then assign a ul to the previous element and continue iteration. Stepping up and down levels as necessary.

[adamwojt]

Any updates on this?

[kura]

@adamwojt commented on 20 Sept 2022, 17:19 UTC:

Any updates on this?

Some of the discussion around this has also happened in a sort of unrelated discussion about replacing pandoc, one of the options for the replacement would come with a [toc] macro bundled in.

[DhruvaSambrani]

@kura does it make sense to add a custom pandoc command option so that people can add whatever changes they want easily? Obviously, this would go against the grain of #70, but I am a huge fan of pandoc and would instead prefer to use the full power of it.

@Linbreux

[kura]

I tried doing this with Pandoc and no matter the approach it did not work. I would welcome any input on getting it working with Pandoc though. - K

…

On 1 Dec 2022, 22:16 +0000, Dhruva Sambrani ***@***.***>, wrote: @kura does it make sense to add a custom pandoc command option so that people can add whatever changes they want easily? Obviously, this would go against the grain of #70, but I am a huge fan of pandoc and would instead prefer to use the full power of it. — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.Message ID: ***@***.***>