Feature Request: Parse markdown by adding sections for each header

[schlichtanders]

Hi,

just tried to implement an interactive table-of-contents for Franklin markdown, but phased a crucial difficulty.

Concretely, header sections of the markdown are currently only translated to an respective headings h1, h2, h3, each with lovely ids.
It would be awesome to have in addition a section structure, so that for each heading id there is a section including the whole document part until the next heading of same level.

So instead of

<h1 id="first_title"> ... </h1>
<p> ... </p>
<p> ... </p>
<p> ... </p>
<h1 id="second_title"> ... </h1>
<p> ... </p>
<p> ... </p>
<p> ... </p>

we would have

<section id="first_title">
<h1 id="first_title"> ... </h1>
<p> ... </p>
<p> ... </p>
<p> ... </p>
</section>
<section id="second_title">
<h1 id="second_title"> ... </h1>
<p> ... </p>
<p> ... </p>
<p> ... </p>
</section>

Please also take a look at this nice example of implementing an interactive table-of-contents in only a very few lines of code It requires exactly these sections elements.

[tlienart]

I'm not in favour of adding this kind of stuff by default as that would lead to unused tags for many users (also detecting whether a section should be closed is not trivial).

Now there's something that would allow you to do something pretty close to what you want and it's to write a begin/end environment (see also https://franklinjl.org/demos/#008_custom_environments_and_commands for more details). In your case you'd write

\begin{section}{Foo bar}
Content (markdown here)
\end{section}

which would translate to what you said. It's maybe not as simple as # foo bar which would do it automatically but it's not far.

To reproduce the title -> id thing (to use the same id in the section and the header), you could define the environment in a function so function env_section(...) and use Franklin.refstring(title).

There's kind of something like this in PkgPage: https://github.com/tlienart/PkgPage.jl/blob/7993cc04e359348c8d09f70ce44344a1e5d4e4a9/src/latex/environments.jl#L30-L60

[schlichtanders]

Thank you very much for your help here.
I was not aware of the environment functions. They look very powerful and will do for my usecase.

You don't have to add such section information by default, you can make it optional.
A section is closed if another header of the same or higher level appears, or at the end of the file, or if a closing tag appears which had no beginning (for the case that someone has a reason to put footer stuff not into foot.html but the markdown itself).
That may not be trivial, but well defined.

I can understand if such an option is very special and because of this not worth adding to Franklin.
Please feel free to close this issue then.

[tlienart]

Before I close this, do you know of another SSG that has something like what you wanted? I'd be interested to have a look.

[schlichtanders]

I unfortunately only have the link above where such section structure is really decisive.

Then I simply realized how natural it would be to add this extra information by default to markdown documents. No experience with other SSG, just felt natural to me.