Including JS in specific pages in Sphinx

[chrisjsewell]

In a number of our packages (sphinx-tabs, sphinx-togglebuttons, sphinx-copybutton, ..) we load JavaScript into the page to achieve something.

Depending on the JS payload, this slow down page loads, which is never ideal.
Writing a website from scratch, you would only include script in your page when they are needed, but in the Sphinx this does not seem possible in a trivial manner.

So what is the best way to achieve this in Sphinx? Is there a way that does not involve delving into the depths of sphinx, or is there a PR that could be made to sphinx to help this?

Basically in a particular extension you can note which docs the JS is required in, by adding an attribute to the env (e.g. during a Directive.run), but its how to utilise this later down the line, during the HTML build phase.

[akhmerov]

Isn't this done by Domains right now?

[chrisjsewell]

Isn't this done by Domains right now?

🤷 Do you have an example?

I know that mathjax checks if there is math in any of the pages (via the math domain), and only includes the JS if there is. But this still adds the JS to every page, even if you only have one math directive on a single page.

[akhmerov]

My bad, you're right. I thought mathjax works on a per page basis.

I'm +:100: on this. Would be great to not embed 50 copies of plotly in a document (and/or not load plotly with each docs page).

I hope this could be somehow done by properly using the sphinx machinery though: as time goes, we're breaking the sphinx pipeline more and more.

[akhmerov]

Coincidentally a highly relevant post in sphinx discussions: https://groups.google.com/g/sphinx-users/c/c4iV3vlsrWk

[chrisjsewell]

Not coincidental lol, this who I was talking to before opening this issue

[pradyunsg]

executablebooks/sphinx-panels#28 (comment)

I totally did not post my comment on the wrong issue earlier. :P

[chrisjsewell]

Wherever it is, I think it's a very viable solution 😀

[stefanodavid]

Coincidentally a highly relevant post in sphinx discussions: https://groups.google.com/g/sphinx-users/c/c4iV3vlsrWk

I don't believe in coincidences... 😊 I just forgot to mention it here

[akhmerov]

Another relevant recent discussion with more replies: https://groups.google.com/g/sphinx-users/c/Z-wcktOhIAc (and more familiar faces)