Skip to content
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

Merged
merged 23 commits into from
Dec 29, 2020
Merged

New Table of Contents element #30

merged 23 commits into from
Dec 29, 2020

Conversation

shashankp
Copy link
Contributor

@Datseris
Copy link

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.

@fonsp
Copy link
Member

fonsp commented Sep 10, 2020

Yeah we can just add an option for position: fixed, right @shashankp ?

@shashankp
Copy link
Contributor Author

@Datseris very true; will look into @fonsp suggestion; probably as an option to either keep in cell or move aside

@Datseris
Copy link

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")]

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)

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)

Copy link
Contributor Author

@shashankp shashankp Sep 12, 2020

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.

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)

Copy link
Contributor Author

@shashankp shashankp Sep 12, 2020

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.

Copy link

@Datseris Datseris Sep 12, 2020

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.

Copy link
Contributor Author

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 🤔

@shashankp
Copy link
Contributor Author

shashankp commented Sep 12, 2020

Using an existing element, but needs more appropriate colors

image

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.
Feedback welcome.
@marius311

@shashankp shashankp marked this pull request as draft September 12, 2020 22:03
@marius311
Copy link

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.

@shashankp shashankp marked this pull request as ready for review September 13, 2020 11:16
@shashankp shashankp marked this pull request as draft September 13, 2020 11:17
@shashankp
Copy link
Contributor Author

Thank you for the inputs @marius311

✔ Improved UX
~ Instant updates - work in progress

image

@shashankp shashankp marked this pull request as ready for review September 16, 2020 20:01
@fonsp
Copy link
Member

fonsp commented Sep 16, 2020

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. indent and aside) on the toc element. Otherwise two ToC elements would interfere, altough that's a rare use case.

@mossr
Copy link
Contributor

mossr commented Oct 6, 2020

It does move to the corresponding cell, but it puts the header in the middle of the window (instead of at the top).

Here's a video of what I mean:

table-of-contents-pluto-hdeader

@mossr
Copy link
Contributor

mossr commented Oct 6, 2020

Also @Datseris, I suppose this is the demo GIF you're looking for 😊

@fonsp
Copy link
Member

fonsp commented Oct 15, 2020

Can you move it to its own file? :)

Copy link
Member

@fonsp fonsp left a 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

Copy link
Contributor Author

@shashankp shashankp left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done

@shashankp shashankp requested a review from fonsp November 7, 2020 17:33
@j-fu
Copy link
Contributor

j-fu commented Nov 13, 2020

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...

@j-fu
Copy link
Contributor

j-fu commented Nov 26, 2020

bump this :)

@fonsp fonsp merged commit 6551162 into JuliaPluto:master Dec 29, 2020
@fonsp
Copy link
Member

fonsp commented Dec 29, 2020

Thanks everyone!

@icweaver
Copy link
Contributor

It's beautiful!! Y'all are amazing 🚀🚀🚀

Screenshot_2020-12-29_17-11-04

@shashankp shashankp deleted the TableOfContents-element branch January 3, 2021 19:02
@MasonProtter
Copy link
Contributor

So I see there's a docstring for the TableOfContents object, but it doesn't show up in https://juliahub.com/docs/PlutoUI/abXFp/0.6.3/autodocs/

Do the docs need to be rebuilt?

@shashankp
Copy link
Contributor Author

So I see there's a docstring for the TableOfContents object, but it doesn't show up in https://juliahub.com/docs/PlutoUI/abXFp/0.6.3/autodocs/

Do the docs need to be rebuilt?

I guess the docs are not generated cos the TableOfContents struct is enclosed in a begin..end
cos of its macro usage (Base.@kwdef)

@MasonProtter
Copy link
Contributor

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

@m3g
Copy link

m3g commented Apr 14, 2021

Is this released? I could not find how to use it at the end. Thanks.

@feanor12
Copy link
Contributor

feanor12 commented Apr 14, 2021

Put this in a cell:

begin
  using PlutoUI
  TableOfContents()
end

@ccmejia
Copy link

ccmejia commented Sep 15, 2021

It's beautiful!! Y'all are amazing 🚀🚀🚀

Screenshot_2020-12-29_17-11-04

Really nice! Do you have a repo for this?
Thanks!
Crist.

@icweaver
Copy link
Contributor

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

@ccmejia
Copy link

ccmejia commented Sep 15, 2021

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?

@icweaver
Copy link
Contributor

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.