Add TOC sidebar

[TristanCacqueray]

fixes #11

• Add JS to highlight the current toc content in view
• Add template setting to toggle toc display
• Documentation and changelog

[TristanCacqueray]

Got something working, pleasantly surprised that heist render templates recursively!

[TristanCacqueray]

@srid this PR now highlights the TOC of the section that is the closer to the top. Though, I was not able to make the sidebar sticky like in this demo: https://tailwindflex.com/@lucas-m/sticky-left-sidebar/fullscreen-preview . I guess one of the parent element is breaking the effect, would you know how to fix it?

[srid]

Yea, Heist is quite powerful, though sadly it seems to be unmaintained, which is one of the reasons @lucasvreis created https://github.com/lucasvreis/ondim I think.

Great to see all this progress, @TristanCacqueray ! Once the functionality is in, let me know - we can figure out UI/design (and refactor) at the end of the PR.

[TristanCacqueray]

I found heist quite tricky to understand, but thanks to your usage code, it's starting to make sense. I would not mind using something else though, like ondim looks great.

I recently tried mkdocs and jekyll, but I missed ema live reload (on top of all the great emanote features), so I'm glad to be able to contribute some missing bits here and there. Thank you for merging my changes!

[TristanCacqueray]

@srid it's not the prettiest TOC, but it is functional now. I couldn't make it stick under the node title, but by floating it out at the same level of the sidebar, it works as expected. Therefor, I'm marking this PR as ready for review.

Also note that the links are affected by the same issue as the regular anchor in live preview (e.g. it sometimes scroll to the bottom).

[soficshift]

one of the reasons @lucasvreis created https://github.com/lucasvreis/ondim I think.

This was one of the reasons, but mainly because I wanted to export to other formats besides html (right now it supports HTML, JSON, Pandoc, LaTeX and a format similar to Mustache which I called Whiskers). I think it's pretty usable now, it's just missing more docs before I can push it to hackage...

I also found that in Heist it was hard to understand what was going on when the templates didn't work. Ondim is hopefully simpler, it also supports recursion (it's like a macro language), has proper "namespaces" and displays error messages with traces.

[srid]

it's just missing more docs before I can push it to hackage...

Once this is done, I'd like to consider using ondim in Emanote.

[srid]

Heads up: international travel upcoming ... might be a while before I get to this PR (which I do want to merge eventually).

[TristanCacqueray]

No hurries, have a safe trip!

[srid]

I'd like to do a few things of things before merging this:

1. Fix Anchor links often scroll to bottom of page #511
2. Improve styling
3. Make TOC positioning look like https://docusaurus.io/ - ie., the TOC sidebar should appear below the title bar, and it should have same background as body.

@TristanCacqueray Would you be able to do (3)? I can do the others.

Basically when you look at TOC-less page like http://127.0.0.1:9010/guide the design should be same as that of the master page. This is how Docusaurus behaves.

[TristanCacqueray]

@srid sounds good to me. I failed to do (3) earlier, and I'll probably need a breakthrough in my understanding of CSS, but I can try again this week end.

It looks like there is something in the outer div that is preventing the toc to stick under the title. As an example, there is also https://typst.app/docs/reference/syntax/ which looks great, but the left bar is not sticking. And for docusaurus, both sidebars stick, but the TOC does not looks like to appear below the title bar. So maybe the challenge to have two sticky elements attached at different levels?

[srid]

@TristanCacqueray With the latest commit in this PR, that janky anchor scrolling should now be fixed! This makes the TOC UX much nicer to work with in live server.

[TristanCacqueray]

I managed to make the double sticky sidebar works in this gist: https://gist.github.com/TristanCacqueray/17980e6701ccea630c3f5cb73cf68eee . I found the issue with the emanote templates, it seems like the overflow-x-auto on the body top div breaks the stickyness!

@srid I think 8a24682 is what you want, though I am not sure how to handle the case where the toc is not enabled. Presently we need to wrap the body so we need an else branch for the <ema:has:toc>. Should we had a new bool variable like <ema:has:no-toc> ?

[TristanCacqueray]

Alas, this solution doesn't work well for the JSON export guide page :/

[srid]

<else /> already exists, for example:

Let me take a look at your PR ...

[srid]

has:toc should automatically be false if the document has no headings, irrespective of what the user has set in their YAML config.

In combination with <else /> (like it is used in sidebar rendering), it should do what you what.

One thing I found was that the page width increases beyond browser width in certain pages, like the markdown.md page. See below. Yes, the JSON export page suffers from the same problem. @TristanCacqueray If you want to give this some more try feel free to, and after that let me know - so I'll resume this PR.

[TristanCacqueray]

I'll try again tomorrow, I'd like to understand how that sticky css stuff works!

[TristanCacqueray]

@srid so it seems like the overflow happens for the notes that have a code block. That is quite mysterious because changing the CodeBlock template had no effect. Using a grid instead of flex layout to separate the body and the TOC seems to work better, as demonstrated in de359e3 .

One little issue remains for short pages like guide/yaml-config, there the TOC gets prematurely pushed up by the footer, not sure how to prevent that beside by moving the footer inside the grid under the note body.

Also, it's hard to reproduce, but sometime the browser becomes really slow, not sure if that's caused by the highlightToc call, or if this is just a side effect of using morphdom.

Lastly, we should automatically disable the TOC when there are no headings, like in the architecture page, and the neuron layout also needs some adjustment.

[srid]

I made some tweaks. The neuron layout is fine -- we can tell user to disable toc along with sidebar.

As for highlightToc, do we really need JavaScript? I see a NoJS solution here: https://codepen.io/davorsuljic/embed/vYgqKWe? (via the comments from https://css-tricks.com/sticky-table-of-contents-with-scrolling-active-states/ )

[srid]

One little issue remains for short pages like guide/yaml-config, there the TOC gets prematurely pushed up by the footer, not sure how to prevent that beside by moving the footer inside the grid under the note body.

I don't see this, btw. Do you have a screenshot?

[TristanCacqueray]

One little issue remains for short pages like guide/yaml-config, there the TOC gets prematurely pushed up by the footer, not sure how to prevent that beside by moving the footer inside the grid under the note body.

I don't see this, btw. Do you have a screenshot?

Not sure what you did, but it no longer happens.

I made some tweaks.

Thanks, it looks great to me!

As for highlightToc, do we really need JavaScript? I see a NoJS solution here: https://codepen.io/davorsuljic/embed/vYgqKWe? (via the comments from https://css-tricks.com/sticky-table-of-contents-with-scrolling-active-states/ )

What kind of sorcery is that!? I guess that requires wrapping the heading and their content with extra sections element to trigger the magic. Looks great, I like how it can highlight sub heading too.

[srid]

I'd like to get rid of JavaScript, but let's do it in separate PR: #520

I'm unsure about the onscroll code's performance; if it ever becomes a problem on the static site, I'll just disable it.

[TristanCacqueray]

That's amazing, thank you @srid for pushing the last bits!