docsy
docsy copied to clipboard
google
Build the right-side table of contents from javascript
By default, Docsy shows the table of contents for the current page in the right sidebar using the built-in function of Hugo. You can replace that with a JavaScript-based ToC that uses the [https://tscanlin.github.io/tocbot/](Tocbot library) by setting the following in your config.toml file:
[params.jstoc]
enable = true
Compared to the default sidebar ToC, this solution:
- has a marker that shows the current location of the screen (useful for long pages)
- shows the correct title even if the title contains a shortcode
- shows the title in the toc even if it was included from another file
For a working example, see https://kube-logging.dev/docs/
Thanks @jmichelgarcia, glad you like it! Rebased and resolved conflicts. @chalin , might you have some time to review this PR?
@fekete-robert would you be willing to rebase this against main?
If you're not sure what that means, reply here and someone who does know how may be able to make time to guide you through that.
Hi @sftim, sorry I didn't intend to close it, just messed something up during the rebase.
@sftim : It seems that the tocbot release archive (https://github.com/tscanlin/tocbot/releases/tag/v4.12.0) contain only the minified version (that is, the same minified file under the tocbot.min.js and tocbot.js name), so I don't think it makes any difference.
The highlighting is not very visible on the screenshot, because not the entire title is highlighted, just the section of the vertical splitbar next to the title. It's more apparent when you are actually scrolling on the page.
Tocbot is MIT-licensed which AFAIK permits free use - is there anything we should do?
On Tue, Oct 18, 2022 at 4:33 PM Tim Bannister @.***> wrote:
How are we honoring the tocbot LICENSE?
— Reply to this email directly, view it on GitHub https://github.com/google/docsy/pull/1049#issuecomment-1282495128, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA6AU3PZ3AC7ZMCEUZ6JZN3WD2YLDANCNFSM5Y3GHUZQ . You are receiving this because you modified the open/close state.Message ID: @.***>
BTW, many thanks for the thorough review!
On Tue, Oct 18, 2022 at 4:38 PM Robert Fekete @.***> wrote:
Tocbot is MIT-licensed which AFAIK permits free use - is there anything we should do?
On Tue, Oct 18, 2022 at 4:33 PM Tim Bannister @.***> wrote:
How are we honoring the tocbot LICENSE?
— Reply to this email directly, view it on GitHub https://github.com/google/docsy/pull/1049#issuecomment-1282495128, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA6AU3PZ3AC7ZMCEUZ6JZN3WD2YLDANCNFSM5Y3GHUZQ . You are receiving this because you modified the open/close state.Message ID: @.***>
Hi, @fekete-robert. Thank you for your work and the update! This is a better and complete solution for the ToC feature.🙂
Although using the original tocbot code itself is allowed by MIT License, it also requires including the original MIT License in the copied code (please refer to the original LICENSE here: tocbot/LICENSE at master · tscanlin/tocbot · GitHub - https://github.com/tscanlin/tocbot/blob/master/LICENSE#L12-L13). So I think one option could be to include the entire MIT License text as a code comment in static/js/tocbot.min.js and static/scss/tocbot.css.
Also, I'd recommend including the original URL and tocbot version so that we can easily track the version and refer to it during a future update.
@shuuji3 Many thanks for spotting that, I've added the licenses and updated the js/css to use a newer version (4.21.0)
I still have hope that this will get merged one day. 🥇
Me too. I realize that this PR pulls in tocbot.min.js from static folder. Since tocbot is actively maintained —latest version is 4.25.0, while this PR still uses 4.21.0— it might be useful to pull in the latest version of the script from CDN at build time via hugo's resources.GetRemote function.
@chalin: any timeline for this PR? I'm surprised to see that this PR is not assigned to any of the existing milestones yet :worried:.
@deining: If I have some time this weekend I'll update the PR to use the CDN, and resolve the conflicts as well. (Originally I didn't use the CDN because I prefer to use local copies, and was also hoping that https://github.com/google/docsy/pull/1204 gets merged, and wanted to use that approach )