Allow TOC element to be fully customizable

[pauloxnet]

[TOC]
# Header 1

will currently generate the following HTML:

<div class="toc">
  <ul>
    <li><a href="#header-1">Header 1</a></li>
  </ul>
</div>
<h1 id="header-1">Header 1</h1>

The div element cannot be changed and so it is for the title span element and its toctitle class.

I suggest that other config parameters (toc_tag, title_class, title_tag) that defaults to their current defaults are introduced.

This would be very useful for producing semantic HTML, using specific HMTL elements.

For example to use the details disclosure element as toc, the extension could be called like so:

md = markdown.Markdown(extensions=[TocExtension(
    title='Summary',
    title_class="",
    title_tag="summary",
    toc_class="",
    toc_tag="details"
)]]

<details>
<summary>Summary</summary>
<ul>
<li><a href="#header">Header</a></li>
</ul>
</details>
<h1 id="header">Header</h1>

This will render an initially closed details element with a summary:

---

Summary

• Header

Header

[waylan]

Interesting request. However, where do we draw the line on feature creep? My knee-jerk reaction is to suggest that one can subclass and/or fork the extension and use your own third party extension which behaves as you desire. That said, the actually changes to implement the requested behavior are rather minimal.

And then we have two different requests here.

1. First we have the request to make an existing class configurable. We already have other classes configurable, so this seems reasonable.
2. And then we have the request to configure the actual elements (div vs. details etc.). That is not something we have done traditionally with any of our extensions. I'm much more resistant to do this.

Anyone else have any thoughts?

[facelessuser]

If I had to guess, number 2 is probably the big motivating factor driving this request. There are plenty of documentation sites that I've seen showing tables of contents in this fashion (with details). The idea of generating TOC in a details vs a div doesn't seem that out there to me, but I understand the idea that this could be implemented as an external extension as well. I don't think that I personally have an issue with the request.

I'm not entirely sure how many different ways people want to generate TOCs though either, does it need to be fully configurable to any tag? Or is just an alternative details mode sufficient?

[pauloxnet]

Thanks for your feedback.

My final goal is to add a way to generate the table of contents using the "details" element and I have proposed a flexible and retro-compatible implementation, but I guess that is not the only one possible.

For instance:

1. Do you think it might be a better solution to directly replace the classic "div" element with "details" and "span" with "summary" (not retro-compatible) ?
2. Or would you rather just add a boolean key in the configuration to choose between the "div" and "details" toc version (reto-compatible) ?

[waylan]

First, I will note that this is certainly not the first request to alter the markup for TOC. However, previous requests have asked for different changes (like not using a UL, for example). The most flexible approach would be to provide some sort of templating option (user provides a template with a default fallback). However, that adds an additional layer of complexity that we don't want to deal with. However, I think it would make for a great third-party extension and could possibly be popular with a subset of our users. Personally, I think that would be the most desirable solution from my perspective.

The original purpose of the existing extension was to mirror the behavior of preexisting extensions for other implementations (PHP Markdown Extra and MultiMarkdown specifically). As far as I am aware, of the three, ours is already the most flexible in its output. I feel like allowing configuration of the markup is perhaps a step to far. That is, unless you can point to other pre-existing implementations which do so.

[pauloxnet]

I understand your point of view, but I think it's good that Python Markdown has evolved from its original purpose. I would suggest improving further without being swayed if the other extensions are stuck on older HTML versions.

Looking at my PR code at the moment, I don't see any unwanted effects, but it is possible that I may not be able to understand all the implications of my proposed change. If so, thank you anyway for the time dedicated to this review and obviously to all the work done.

My original intent was just to try to make an improvement contribution to a library that I have been using for long time.

[waylan]

Looking at my PR code at the moment, I don't see any unwanted effects, but it is possible that I may not be able to understand all the implications of my proposed change

No that's not it. Your changes look good. It's more about scope.

Perhaps I should have begun by pointing to the toc_tokens attribute. As documented, a nested list of tokens are available in addition to the preformatted HTML. From that list of tokens, one can format their own TOC using whatever tools they are using to wrap the HTML output of Markdown. In fact, since that feature was added, I have been hesitant to add any additional features which modify the default output. Using toc_tokens is preferred.

In other words, it is possible to do what you want without any modifications to the extension. so long as you don't use the `[TOC]' marker. In my experience, having the TOC separate from the body content is preferable in most environments anyway.

Except for backward compatibility reasons, I would prefer to remove any options which are used solely to modify the HTML output of the TOC and require all such modifications to make use of the toc_tokens to build a custom formatted TOC.

[pauloxnet]

... Your changes look good. It's more about scope.

Perhaps I should have begun by pointing to the toc_tokens attribute ...

The goal of my contribution was to get markdown files that already contain the [toc] statement to be rendered with more modern HTML code with as little effort as possible for the user of this library.

I don't understand how I can use toc_tokens to get a table of contents that uses the details and summary elements without modifying existing files.

Your point about scope is not clear to me, but I accept if as a maintainer you want to reject my PR and close this issue.

BTW thanks to maintain this great library.

[waylan]

Your point about scope is not clear to me,

The concern is that if we allow the user to customize some of the generated markup, then the user will understandable ask to be able to change other parts of the generated markup. To avoid that, we don't include support for changing any of the markup. That feature is out-of-scope for this extension. If a user wants to use different markup, then they need to use a different solution.

The different solution that we provide is toc_tokens. Of course, that means not using the [toc] marker which, yes, means that you would need to edit/make changes to your documents and templates. Although, you could disable the toc extension's marker option and create your own extension which gets the toc_tokens from the toc extension and uses that to build your custom markup and swap that in for the marker. There would be no need to edit your files then.

I'm closing this as wontfix.