-
Notifications
You must be signed in to change notification settings - Fork 56
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
New Table of Contents element #30
Conversation
My personal opinion, and motivation behind #307 is that a table of contents is much, much more useful when it is always visible, i.e. in the side bar. Having it only at the top of a 30 page long to document takes away a lot of the benefits I would say. Of course, it is still useful to have, and a good start. But, while scrolling all the way to the top to find it, I probably will come across the section I needed to find anyway. |
Yeah we can just add an option for |
you rock, keep it up! |
src/Builtins.jl
Outdated
) | ||
).map(el => el.id) | ||
|
||
const headers = [...elementsOfType("h1"), ...elementsOfType("h2"),...elementsOfType("h3"),...elementsOfType("h4"), ...elementsOfType("h5"),...elementsOfType("h6")] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would it make sense to have the allowed headers as input argument? E.g. the user would provide the level depth they require (1 to 6) and only headers up to this depth are used in the ToC?
If LaTeX has any value here, I would argue that the default depth should be 3 (because in latex by default you get section numbering up to e.g. 2.2.3
)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(but this is a minor comment - please don't let it hold this PR back)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added the depth limit. ✅
Tempted to do auto numbering, but wouldn't it be jarring? a section name would have a number in the TOC, but not in the actual location. I'd rather let user do the numbering.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't know how the plugin of Jupyter does it, but the autonumbering there is reflected in both the TOC and the headers. So the headers will literally display 1.1 Header. But maybe this is too invasive or just too hard to do from the design of Pluto?
(to be honest I actually liked the auto numbering)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, updating the user created content itself would be invasive & fraught with assumptions.
Lets see the feedback on auto-numbering only in TOC.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've checked Jupyter again and they only change the display. So if I have markdown sections:
# Title
## Subtitle
# Next title
they will be displayed (or rendered) as "1. Title, 1.1 Subtitle, 2. Next title", but when I double click the markdown cells to edit them, the numbers are not there. So it is only what displayed that is altered and thus I would call it non-invasive.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Header cells would need to store the numbering in their state making them special markdown cells. Adding this hidden state from an external PlutoUI addon seems invasive 🤔
Using an existing element, but needs more appropriate colors Is a regular element for smaller screen widths; this case would need an animation on the target element shoulder when clicked as it will scroll to target. Looking into reactive updates; was running into into recursive updates Really liked Observable's navigation, but thats cell based, not necessarily header links. |
Thanks for the tag, just tried it out and looks great already, plus super happy to see its being worked on since a TOC is a must-have for all but the shortest toy notebooks. Only quick comments I have is the chunky blue box looks slightly out of place in the Pluto UI, I think something sleeker with either a 1px border or even just a top border which matches the cells themselves would be better, but I'm sure you're going to play around it (and really happy to see the same-sized font + indent approach to showing depth, instead of the visual mess that JupyterLab's many-font-size TOC is still after many years 😄 ) And right now you have to re-evaluate the TOC cell for it to pick up changes to headings, but probably you're working on that too. |
Thank you for the inputs @marius311 ✔ Improved UX |
Instead of switching the visual style using if condition
print(io, some_extra_css)
end it would be nicer to always output that CSS, and switch the style by including or not including a class (e.g. |
Also @Datseris, I suppose this is the demo GIF you're looking for 😊 |
Can you move it to its own file? :) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you move it to its own file? It is not a HTML5 builtin
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
Hi, tried this out - IMHO it's ready to go... Would use it immediately. EDIT: it seems that the global link color has changed. Being non-intrusive as it is now in the TOC is perfect, but in normal text IMHO highlighting is now slightly too weak. Matter of taste of course... |
bump this :) |
Thanks everyone! |
So I see there's a docstring for the Do the docs need to be rebuilt? |
I guess the docs are not generated cos the TableOfContents struct is enclosed in a begin..end |
Hm, I don't see that happening at the REPL: julia> begin
"""
docstring
"""
Base.@kwdef struct Foo
a = 1
end
x = 2
end
2
help?> Foo
search: Foo floor pointer_from_objref OverflowError RoundFromZero unsafe_copyto! functionloc StackOverflowError @functionloc
docstring
|
Is this released? I could not find how to use it at the end. Thanks. |
Put this in a cell: begin
using PlutoUI
TableOfContents()
end |
Oh, this is from the MIT course that @fonsp and others were involved in getting off the ground last Fall. I would definitely recommend checking out their updated Spring course when you have the time! The repository can be found here |
Thank you for your quick reply! I had problems with the aside option for table of contents... It came from my zoom configuration of navigator... I need new glasses... How could you enable the dark view? |
I like using DarkMode. Dark Reader is also nice for just editing the CSS directly through your browser. I've also seen PlutoStyles.jl, but have not used it myself |
https://github.com/fonsp/Pluto.jl/issues/307