search

nunocoracao / blowfish

Personal Website & Blog Theme for Hugo
https://blowfish.page
MIT License
1.37k stars 382 forks source link

🖌️ Long ToCs not shown fully #1474

Closed wermos closed 2 months ago

wermos commented 4 months ago

Description

A good example of the bug is in the documentation itself, here. When the table of contents is really long, it is impossible to see all the options until you scroll to the bottom of the page.

Expected behavior

One relatively simple solution I can think of, is to make the ToC scrollable, independent of the main page's scroll.

Screenshots

image

In the above screenshot, it is not possible to see the text below "Firebase" until you scroll to the bottom of the page.

Desktop (please complete the following information): Even though I don't think it's applicable here, I'll fill it regardless.

maciejopalinski commented 4 months ago

The table of content definitely should NOT be scrollable independently of the main page's content. It would look very bad.

wermos commented 4 months ago

My proposed solution was just the first thing that came to mind. I am open to other solutions.

Usual-Coder commented 3 months ago

Hi,

Even if we are a minority, may we disagree on the bold (subjective) statement "(...it) should NOT be scrollable (...) It would look very bad" ?!

Typing "Best Practices" + "Table of Contents" in your preferred search engine may show you how many (different) opinions you can have about the "how to do things properly".

That being said, the purpose of a ToC is to provide a way to be able to "jump" quickly anywhere in your document (online / offline ... or even printed = your fingers doing the same job as your browser 😅).

So, even if a majority disagree, some of us may be allowed to think that making it available only partially (I agree the configuration page of Blowfish website is not that big 😅 ... but it was just an example) is not the best/expected behavior.

The same way, @nunocoracao may not give a damn about it, think it's too much work for a too small audience ... or have other priorities 🤷

In worst case, we'll have to switch to another (rare) theme providing this kind of feature, mainly for docs (like Doks) or learning (ex.: Relearn), but, on a more subjective point of view, most of them are not as nice/polished as Blowfish 😅

On a more constructive note (having filled the issue #1455, marked as closed a little too fast 😇, for the very same reasons), may I propose: (in order of priority, as I see them)

  1. at least a smartTOCPosition configuration entry, so those producing big documents can benefit from a "full ToC" placed at the beginning/end, the same way Blowfish handles posts series = the behavior / responsiveness / etc. being already implemented, it should be easily adapted 🤔

  2. to keep the ToC "in sync" with the main content (the anchor in the main panel should be visible in the ToC lateral panel)

  3. a smartTOCBehavior configuration entry, allowing collapsible and/or scrollable ... for those who like it that way 😅

May I end by saying that the choice should always be given to users. But time being such a rare commodity, as always, @nunocoracao will have the final say ... thanks for considering this 🙇

maciejopalinski commented 3 months ago

Even if we are a minority, may we disagree on the bold (subjective) statement "(...it) should NOT be scrollable (...) It would look very bad" ?!

Typing "Best Practices" + "Table of Contents" in your preferred search engine may show you how many (different) opinions you can have about the "how to do things properly".

I have never seen a scrollable table of contents placed in similar way like the one in Blowfish. I suppose that's for a reason, because it would be an objectively bad design choice. If you think otherwise then show some examples on other websites and implement it in Blowfish as a proof of concept.

Usual-Coder commented 3 months ago

I'm not here to convince people who own the absolute truth to be more open-minded or take a better look at what is available outside.

And, no matter this too often passive-aggressive attitude we bump into, when discussing different opinions, and the way of presenting your own as the only possible way of thinking, since I don't pretend to own it myself but merely consider a constructive approach to (start with) fill(ing) issues and try improving things by doing so, maybe we should let @nunocoracao answer this one by himself ?!

And as I said previously / many times in other issues, if he thinks it's not appropriate to fix/add this feature to this project/theme ... that's more than ok 🤷

Blowfish is already a very good theme and we are all thankful for his time and the fact he is providing it freely to the community (and can also add thanks for you 2 commits last year and the other ones who helped him, no matter how (much) they've contributed) 🙇

For those who may be unhappy with his answer and/or don't have the availability/knowledge/whatev to implement this feature, they'll still have the possibility to search for a better-fitting theme, as pointed previously 🤷

Hoping for an answer soon so we can stop wasting time/energy talking about it and more building/producing things 🤷

Best regards to you all. 🙇

maciejopalinski commented 3 months ago

I'm not here to convince people who own the absolute truth to be more open-minded or take a better look at what is available outside. And, no matter this too often passive-aggressive attitude we bump into

There is nothing passive-aggressive about my simple request for a proof of concept when suggesting a change. That is just how open source software development works. How to contribute to Blowfish: New features & enhancements

wermos commented 3 months ago

@maciejopalinski Do you agree that not being able to see the full ToC is a problem? If not, why not? If yes, then do you have any suggestions that are not, in your words, "an objectively bad design choice"? Since I am not a designer, and I suspect @Usual-Coder is not either, could you please enlighten us about some good design choices?

Also, your remark:

I have never seen a scrollable table of contents... because it would be an objectively bad design choice.

is disingenuous, and not constructive. I think that's what @Usual-Coder was trying to say.

wermos commented 3 months ago

If you think otherwise then show some examples on other websites

Sure. Wikipedia. Here's a link to a page with a long ToC. I'm using the Vector (2022) layout, which should be the default for everyone. If not, you can set the skin to Vector (2022) temporarily, to see what it looks like.

For your convenience, I am also attaching a screenshot of what it looks like on my device: image

maciejopalinski commented 3 months ago

That looks cool, but it would require to move the ToC to the left. I don't think it necessarily fits the theme. I think the theme was designed mainly with blogs in mind in which you won't really find such long ToCs.

Usual-Coder commented 3 months ago

Hi,

@wermos thanks for your additional input. I decided to cut my losses with Hugo/theming/etc. (too much time lost with the tooling instead of producing content) = at least for now, I'll use another solution :shrug: But, still, I think Blowfish is probably one of the best themes for Hugo :bow: (after all, it's just not fitting our needs / decisions had to be made :shrug:)

To try ending on a constructive note, I'm providing a link to a French website behaving as I expected initially (ToC on the right being scrollable and really kept in sync with content):

I also still understand that @nunocoracao may not have time to implement that (making his smartTOC scrollable, at least as an option, and kept in sync with the main content). As I said, it's his prerogative to determine if it's bug or enhancement ... and how to handle it :shrug: I hope he will fix/add this feature :crossed_fingers:

Best regards to you all

maciejopalinski commented 3 months ago

This one convinced me, I didn't even realize it was scrollable at first, but then I checked and it really is. I apologize for misunderstanding the idea that you suggested. It would definitely be a nice fix/addition to have this indicator and make it scrollable (preferably auto-sync with content; without the scrollbar visible of course).

Usual-Coder commented 3 months ago

@nunocoracao ... if you consider implementing this after all, from the UX designer point of view, to handle sublevels (not presented in the linked URL), may I also suggest replacing (or providing a SmartTOC*** option) your underlined style (some may say we could call it a horizontal bar :smirk:) with the vertical bar shown in the linked website.

By doing so, you could "expand" it in front of the subentries and handle sublevels, adding a similar (expandable, if needed / children) but "sub-leveled" bar, using a darker color from your palette depending on the sublevel (the most vivid being the deepest one ... aka "keep the focus where it's needed + make the rest useful but discrete" :smirk:).

I'm about to go out right now, if my explanations are not good enough, I may search for an example + add a comment with a link later. Just ask.

wermos commented 3 months ago

@Usual-Coder thanks for the example site link. I can use this to deconstruct how Vitepress does it and perhaps open a PR in Blowfish to implement the same feature. Vitepress's default ToC works exactly how I envisioned the feature to be.

I think Blowfish is probably one of the best themes for Hugo

I wholeheartedly agree. @nunocoracao has done some amazing work here.

The

"sub-leveled" bar

idea sounds pretty interesting to me. I'll play around with it and see if I can implement it along with the Vitepress-style scrollable ToC.

Do you also have an idea for what darker color from the palette could be used here? More specifically, could you help me figure out which color to use for the default blowfish color scheme and the other available skins?

...if my explanations are not good enough, I may search for an example + add a comment with a link later. Just ask.

It would be nice if you could find a site that uses the "sub-leveled" bar so that I have a visual example to go by.

Usual-Coder commented 3 months ago

@wermos: I didn't do much ... that design (scrollable/synced right ToC) is quite common 🤷

To stay around Hugo: https://docs.gethyas.com/install/auto/#starter-templates

The guys from Hyas are the ones behind the Doks theme for Hugo Some would also notice the very nice/useful idea 😇 of the "tabbed" code block (allowing to switch between variants, also used on Hugo website ... btw, even if it's not that long/useful there, the right ToC is also scrollable ... if it's good for Hugo's daddy maybe it could be good for us 🤷😅) = that could also be a killing feature for Blowfish 🤐😇😅

Another one I came across while dealing with what is actually requiring my attention: https://elysiajs.com/patterns/websocket.html (behaving the exact same way as the French blog linked previously ... but I prefer the homogeneity of the linked Blog, nav/toc sharing the same design)

btw, (as shown by the first entry) an option to handle the text overflow of entries too large with an ellipsis could also be an idea to explore 😇 ... but (unlike them) with a mouseover animating the text in place instead of popping a basic tooltip ... as always, with design considerations, the devil / wow effect is in the details / how seamlessly everything is integrated (and/or configurable one would argue)

Right now, I don't have time to search specifically for sublevel design examples, but if I stumble upon a website having such a design, I'll try to remember to provide you with a link ✔

Btw, I can't help you with colors/palette considerations. First, because I think it's @nunocoracao prerogative to answer that one. And second, it would require me to read Blowfish code ... which is the very reason I decided to steer away from Hugo/theming/etc., having already lost too much time ("(...) with the tooling instead of producing content (...)", as I put it earlier 😇).

No matter what, wanting to contribute to Blowfish code base is a very constructive way to handle this issue ... big respect for that 🙇 ... but may I suggest starting with a quickwin™ until @nunocoracao comes in the loop ... and gives his point of view on the subject?! 🤐😇

In the meantime, I would stick with a basic/simpler version like the one available here (getting the inspiration from the left panel/nav): https://bun.sh/docs/bundler/loaders#json

Take a good look at the indicatorS ... couldn't it be a good compromise until you hear back from @nunocoracao about how far you'd be allowed to alter Blowfish design?! 🤐😇🤷

At the end of the day, it's your time, feel free to push the envelope ... that's how great things are built 😅🙇

nunocoracao commented 3 months ago

Oh geez... this was a long one. Sorry for not getting back to any of you sooner. A couple of comments here (sorry if I jumped over some parts this was a long thread to catch up with)

Now, my take on this discussion. I do believe this should be implemented - I will need some time though :D A couple of points on how I see the solution

If the above is not possible, aka it requires redesign than the second best option is to add another config...

Were you planning on working on a PR or do you want me to take this on? - to be clear, it will take me a while to have time to focus on this particular one

wermos commented 3 months ago

Thanks for the response, @nunocoracao!

Sorry for not getting back to any of you sooner.

No worries. Better late than never 😄

Were you planning on working on a PR or do you want me to take this on?

I would feel better if you took this on. I'm only beginning to familiarize myself with the repo, so I'm more comfortable with bug fixes and the like. I spent some time looking at the existing ToC implementation, and I think that fixing this would require me to rewrite the layouts/partials/toc.html file.

Usual-Coder commented 3 months ago

@wermos I'm sorry, I didn't have time to find an example + I'm probably going to unsubscribe soon = won't receive further messages. Having only a draft on how to derive/create a Hugo theme (finishing it is now at the very bottom of my TODO = no task/time will be allotted, at least for a few months), I can't help you further. Sorry. I hope you'll find your own solution.

To end this part on a constructive note / trying to help you contribute ... or build your own solution:

Besides those pointers, I'm sorry I can do much more + I probably won't contribute to Blowfish anyway (if I come back near Hugo / these kinds of time-consuming topics, it will probably mean creating a new theme / everything else to fit my needs) = still I think it's one of the best theme around worth your time / contribution(s) 🤷 Have fun playing with it 😅

@nunocoracao thanks for your answer and don't get me wrong on the "I would prefer to create my own" = I was hoping to fill a gap with Hugo/Blowfish until I had a proper LMS, up and running (some of my needs are related to courses/learning process = I can't afford not having tables of contents behaving the way they should + missing other useful features = the fixing/adding time has to be put in doing it directly in the LMS) = I'm mean it, great job with this theme 🙇. Hope you'll be able to find the time to keep it evolving ... and hopefully the necessary help/contributors 🤞

Best regards to you all 🤘

nunocoracao commented 3 months ago

@wermos @maciejopalinski @Usual-Coder feel free to have a look at https://github.com/nunocoracao/blowfish/pull/1529 A preview link should be there soon to see the differences... this was wayyyyy harder than I expected. Thanks for suggesting this though got to learn some sutff

Usual-Coder commented 3 months ago

@wermos: I thought about creating an example design for you (not having time to read Blowfish code, opening something like Figma seemed rapidly overkill / too far fetch) ... but, since we are never safe from an unexpected/pleasant surprise 😅 ... while answering @nunocoracao I stumble on an example of "sublevels handling" (with vertical indicators) 😅🎉 from one of the previously linked examples = https://elysiajs.com/eden/treaty/overview.html ... on the left (used for global navigation ... but you can extrapolate it for a ToC 😅). I personally like minimalistic designs, so I would consider keeping it even more simple = trying to show only the deepest vertical bar + hide the highest one (replacing it with the same vertical indicator in front of the opened entry). I wouldn't add/mess with the background color (you could consider it useful when trying to keep the info about the main stuff, as it's done on this example ... but I would keep a low/discrete profile for the ToC). (Instead) I would also play with the alpha component of the font (aka opacity) = darkening out of reach entries (obviously restoring full white/black on mouseover) + bold lettering for the parent entry, when opened, and the current one (the child/shown entry) = yep collapsible entries are definitively a must-have with "big docs" ... but that part may also require a lot of work 😇 Remembering, those are only suggestions + opinionated/subjective considerations = I don't own any truth ... feel free to contribute while ignoring them completely 🤷 @nunocoracao is paving the way for many possibilities, don't be afraid to try new things 😉

Just found another example showing something very similar to what I just wrote (ignore the ToC, inspiration could be taken from the navigation on the left): https://clerk.com/docs/authentication/social-connections/gitlab. And this incredible variant (take a look at the ToC on the right), so simple but efficient: https://clerk.com/docs/custom-flows/user-impersonation#revoke-an-actor-token-from-the-backend-api 😱🤩

@nunocoracao (even if I'm not coming back to Hugo/Blowfish, I took a rapid look at your files changes = too many modifications = don't have time to check the PR technically ... Sorry 😞) I'm impressed by your commitment to improve this theme. Great respect for that 🙇 You deserve the interest your theme is picking. I hope you'll get the traction it really deserves 🤞

Now, concerning the PoC/preview you've provided in the PR (doing such a thing/producing this kind of effort is really ~amazing™~ mesmerizing), the following remarks are made per your request (if something is not clear, ask for additional precisions 😅😇):

  1. Per UX fundamentals , given an optional component (scrollbar), it shouldn't be displayed when it's not needed / could be confusing (like 2 scrollbars too close) ... aka _"keep the UI clean as much as possible" + "show only what's necessary"_. Examples linked above don't show any scrollbar = the scrollable area is triggered depending on mouse position = It's not technically needed ... but, as always (it's your prerogative), you could argue you prefer it your way for other reasons (design/whatev)?! 🤷 Your main scrollbar is not shown when it's not needed (ex.: authors page) ... if you want to keep the ToC scrollbar, shouldn't you apply the same logic everywhere?!

On a more subjective/opinionated note, I would have it removed completely + the underline in the Toc is too strong (for my own taste) = I would replace both with vertical indicator(s) in front of the entry(ies), as shown in linked examples.

  1. Improving UX (would probably require even more additional rework 😅😇): a ToC must answer the "where you are" but it could also show the "what is (actually) covered" (like https://bun.sh/docs/bundler/loaders#toml) or point/indicate the "where you go" (useful in learning/teaching context, aka tutorials, courses, processes, etc.), like https://clerk.com/docs/quickstarts/fastify. For that last variant, you could already achieve something quite similar with your Timeline shortcode, for the main page = the ordered ToC is the only missing component 🤐😇

Hope this feedback will help your reflection. 🤷

nunocoracao commented 3 months ago

Thanks @Usual-Coder.

Regarding the design perspective I will definetly play around with it. I also don't like the huge blocks - it came with the lib.

I relied on the markdown sample article and reduced the height of the window to test this. Behavior should be, no scroll when TOC is smaller then height of window - otherwise scroll becomes visible... are you seeing something different?

Usual-Coder commented 3 months ago

Short answer

"no scroll when ToC is smaller than the height of window" may be good enough, for now = it will fix the issue = take the (quick)win 🤷 (and start a discussion "somewhere else" about design + UX considerations with users willing to have constructive contributions / being a force of proposal ... or simply sharing design inspirations 🤷).

Not so short answer 😏

It may not be that simple, depending on what you want to do with it 🤷 I started a detailed answer ... but this issue, already quite long 😅, would have exploded 😇 = obviously (theoretically) you'll always have: ToC (aka component) max-height < (...) < window height (aka presentation area). The (...) representing (optional) things you probably didn't consider/think to implement (for now 🤷).

But, as always, the devil is in the details 😏

Let me give you an example outside of considerations regarding the ToC itself. If we call the ToC a component (not the worst idea, some would say 😅😇) and its parent container a panel (avoiding considerations related to the layout, for the sake of this example / to keep it short 🤐), you may put other components in that panel = a (quick)search form/entry at the top, additional/useful links at the bottom, etc. (take a look at the links) ... you could even have other components right in the middle of the ToC (we are talking evil here ... let's consider ads for those who may try that to monetize their blog / would still think it's possible/sufficient to cover their costs with that kind of annoying things 🤐) = you may have to deal with the height distribution in different ways 🤷 (start having playful usage of CSS variables and other things like that 😏)

Now, talking about the ToC only, you may try to make it really smart™ 😏 aka dynamic ... (line-)height + fading/folding/animating out of reach / unnecessary entries ... even better, not showing the full ToC at all 😱 (may come handy for VERY long docs, procedures, etc.), but adapting displayed entries (depending on the mouse position 🤔) ... etc.

= I could fill your (full-time) backlog for weeks (if not more) just on that topic ... but, without knowing your (real) motivations + where you want to go with your work here (the somewhere else / those discussions may be organized outside GitHub = try building a community around your work, etc. 🤷 yep ... let's just say, I'm a pushing the envelope kind of person 😅), I think it's better to stick with the Pareto principle = fixing this issue, you've probably done enough for your main (aka the 80% 😉) audience 🤷 (and I must go back to my own troubles with very similar topics 😅)

Again, I hope it will help your reflection.

I wish you the best for the rest ... and thanks for the time / fixing this one 🙇

wermos commented 3 months ago

feel free to have a look at #1529

Sorry I wasn't able to get to it sooner, I was a bit busy with some other things.

I took a look at it now, and I am quite satisfied with the result. It definitely addresses this issue in its entirety.

I also think that @Usual-Coder is correct, but further tweaking can always be done in later PRs. I think it's good enough for now. Great work!