8000 Build the right-side table of contents from javascript - updated version by fekete-robert · Pull Request #2273 · google/docsy · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

Build the right-side table of contents from javascript - updated version #2273

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

fekete-robert
Copy link
Collaborator
@fekete-robert fekete-robert commented May 30, 2025

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/

Copy link
google-cla bot commented May 30, 2025

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@fekete-robert
Copy link
Collaborator Author

Update includes a rework based on the katex examples, and gets the tocbot js and css from a cdn.
(It seems there's no latest version tag, so the version number defaults to the the currently available latest version.)

@chalin
Copy link
Collaborator
chalin commented May 30, 2025

Thanks for the updated PR. Can you resolve the CLA issue?

@deining
Copy link
Collaborator
deining commented May 30, 2025

It seems there's no latest version tag, so the version number defaults to the the currently available latest version.

You can try these URLs:

https://cdn.jsdelivr.net/npm/tocbot@latest/dist/tocbot.min.css
https://cdn.jsdelivr.net/npm/tocbot@latest/dist/tocbot.min.js

@deining
Copy link
Collaborator
deining commented May 30, 2025

Update includes a rework based on the katex examples, and gets the tocbot js and css from a cdn.

Were nice if resources.GetRemote fetches minified versions of the files in production mode only. Please have a look at the latest version of the script for the KaTeX files, there this is already implemented:

{{ $katex_js_url := printf "https://cdn.jsdelivr.net/npm/katex@%s/dist/katex%s.js" $version (cond hugo.IsProduction ".min" "") -}}
{{ with try (resources.GetRemote $katex_js_url) -}}
{{ with .Err -}}
{{ errorf "Could not retrieve KaTeX script from CDN. Reason: %s." . -}}
{{ else with.Value -}}
{{ with resources.Copy (printf "js/katex%s.js" (cond hugo.IsProduction ".min" "")) . }}
{{ $secureJS := . | resources.Fingerprint "sha512" -}}
<script defer src="{{- .RelPermalink -}}" integrity="{{- $secureJS.Data.Integrity -}}" crossorigin="anonymous" ></script>
{{ end -}}
{{ end -}}
{{ else -}}
{{ errorf "Invalid KaTeX version %s, could not retrieve this version from CDN." $version -}}
{{ end -}}

@fekete-robert
Copy link
Collaborator Author

Thanks, I'll update the PR when I have some time (probably not before Saturday)

@chalin chalin force-pushed the righ-hand-tocbot-redone branch from 62eb8e6 to db6abf2 Compare June 8, 2025 00:16
@fekete-robert
Copy link
Collaborator Author

BTW, @deining : the error checking part when downloading the css/js file doesn't seem to catch if you specify a version number in the config file but it doesn't exist. (I don't use katex, so haven't checked if it's working there.) Probably not a big issue, I doubt many users will want to set the version manually.

@deining
Copy link
Collaborator
deining commented Jun 8, 2025

BTW, @deining : the error checking part when downloading the css/js file doesn't seem to catch if you specify a version number in the config file but it doesn't exist.

You are right. I'm aware of that, but didn't find the time to dig into that. If you can come up with a solution, welcome!
Looking forward seeing your PR finalized!

@fekete-robert
Copy link
Collaborator Author

Shall I re-break the lines in the userguide, or the broken tests are just informative?

Copy link
Collaborator
@chalin chalin left a comment

Choose a reason for hiding this comment

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

Thanks for the updates @fekete-robert. See inline comments. Also:

  • Enable this feature for the User Guide
  • To fix the GH check failures, run npm run fix:format locally.

Given that this generates the right-sidebar toc, shouldn't we disable toc generation in the appropriate layout file?

@@ -74,6 +74,11 @@
{{ template "algolia/scripts" .Site.Params.search.algolia -}}
{{ end -}}
<script src='{{ "js/tabpane-persist.js" | relURL }}'></script>

{{ if .Site.Params.jstoc.enable -}}
{{- partial "scripts/jstoc.html" . -}}
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
{{- partial "scripts/jstoc.html" . -}}
{{ partial "scripts/jstoc.html" . -}}

@@ -0,0 +1,44 @@
{{ $version := .Site.Params.jstoc.version | default "latest" -}}

{{ $css_url := printf "https://cdn.jsdelivr.net/npm/tocbot@%s/dist/tocbot%s.css" $version (cond hugo.IsProduction ".min" "") -}}
Copy link
Collaborator

Choose a reason for hiding this comment

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

Refactor the code to define $resourceBaseName as tocbot%s using (cond hugo.IsProduction ".min" ""). Note that this variable will be used in four places.


<!-- Initialize tocbot -->
<script type="text/javascript">
tocbot.init({
Copy link
Collaborator

Choose a reason for hiding this comment

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

Use two spaces as the default indentation.

```

By default, h2-h4 headings are included in the sidebar, which includes tips and warnings if you are using the [alert shortcode of Docsy](/docs/adding-content/shortcodes/#alert). To change that,
provide a comma-separated list of the headings to include in the `custom_headings` parameter, for example:
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
provide a comma-separated list of the headings to include in the `custom_headings` parameter, for example:
provide a comma-separated list of the headings to include in the `headings` parameter, for example:

Fix here and elsewhere.


- 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
Copy link
Collaborator

Choose a reason for hiding this comment

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

FYI: this is no longer a limitation when the include functionality is properly coded.

Copy link
Collaborator

Choose a reason for hiding this comment

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

For consistency with the jstoc.js file name, this should be named _jstoc.scss.

@chalin
Copy link
Collaborator
chalin commented Jun 10, 2025

You are right. I'm aware of that, but didn't find the time to dig into that. If you can come up with a solution, welcome!
Looking forward seeing your PR finalized!

@deining or @fekete-robert: please open an issue to track this if there isn't one already.

@deining
Copy link
Collaborator
deining commented Jun 10, 2025

You are right. I'm aware of that, but didn't find the time to dig into that. If you can come up with a solution, welcome!
Looking forward seeing your PR finalized!

@deining: please open an issue to track this if there isn't one already.

Done: PR #2280.

fekete-robert and others added 7 commits June 12, 2025 14:25
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com>
@chalin chalin force-pushed the righ-hand-tocbot-redone branch from 5126b2f to 4f7fdf7 Compare June 12, 2025 18:25
@chalin
Copy link
Collaborator
chalin commented Jun 12, 2025

@fekete-robert - I just was made aware that Bootstrap has a solution to #349. Just a heads up that I'll be exploring the Bootstrap alternative.

@fekete-robert
Copy link
Collaborator Author

Sure thing, it's better to use a built-in component

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.

3 participants
0