offline css and fonts

[kalvdans]

I found out that even with katex_prerender=True the generated documentation wants to fetch katex.min.css from the Internet. I've solved it by installing libjs-katex Ubuntu package and added the following to my conf.py:

html_static_path = ["/usr/share/javascript/katex"]
katex_prerender = True
katex_css_path = "katex.min.css"

The problem is now that the css comes from a different katex version than what was used to render the HTML. I seek advice here how we should solve the problem:

1. Bundle all katex static resources into sphinxcontrib-katex,
2. Make the katex.min.js path configurable in katex-server.js so I can point it to /usr/share/javascript/katex/katex.js, or
3. Don't do anything and leave it to the user to make sure katex_css_path points to the same version as bundled with sphinxcontrib-katex.

[hagenw]

The default behavior at the moment is to fetch katex_css_path from the Internet, see https://sphinxcontrib-katex.readthedocs.io/en/v0.9.9/configuration.html

The KaTeX version set in the config is always set to match the one of the katex-server.js file, which is bundled with the extension to build the package. So there should not be any version mismatch with the default settings.

But I'm also open to changes, e.g. I can't remember why I decided to not bundle the CSS file with the extension together, whereas for the other files it seems to be the case.

[hagenw]

Sorry, I misinterpreted

sphinxcontrib-katex/sphinxcontrib/katex.py

Lines 374 to 388 in 296c71e

	@staticmethod
	def build_command(socket=None, port=None):
	"""KaTeX node build command."""
	cmd = [NODEJS_BINARY, SCRIPT_PATH]
	if socket is not None:
	cmd.extend(["--socket", str(socket)])
	if port is not None:
	cmd.extend(["--port", str(port)])
	if KATEX_PATH:
	cmd.extend(["--katex", str(KATEX_PATH)])
	return cmd

You need to install indeed katex on your system for pre-rendering:

sphinxcontrib-katex/.github/workflows/katex.yml

Lines 35 to 37 in 296c71e

	- name: Prepare KaTeX server
	run: |
	npm install --global katex@${{ env.katex-version }}

So it is possible to get a non-matching katex version.

This will then also not be solved by

1. Bundle all katex static resources into sphinxcontrib-katex

as we will not bundle the katex executable in the extension.

As katex_js_path let's you configure the path to katex.min.js, katex-server.js should maybe be fixed to respect the selected value. But I'm not sure if this could break the server if a version is selected, that is not compatible with the katex-server.js file.

[kalvdans]

You need to install indeed katex on your system for pre-rendering:

I think this is a documentation bug. Only nodejs is needed on the system, and then the bundled katex.min.js is used for pre-rendering. There's nowhere a katex executable is run.

[hagenw]

Thanks for pointing this out. I removed the katex installation from the corresponding test in #124.

And we can also pass on the path to katex.min.js to katex-server.js as proposed by your second solution, as it is set already at

sphinxcontrib-katex/sphinxcontrib/katex.py

Lines 385 to 386 in 77aab65

	if KATEX_PATH:
	cmd.extend(["--katex", str(KATEX_PATH)])

The only thing missing is that this respects the katex_js_path config entry. I will try to update this tomorrow.

[kalvdans]

Thanks yourself @hagenw for swift response and action! I can try out a pull request if you make one for katex_js_path.

[hagenw]

I have now released version 0.9.10, including the changes from #128

[kalvdans]

Great!

@hagenw , you wanted to keep the bug open for some thoughts in #128 (comment) , can you explain it in more detail here?

[hagenw]

Yes, at the moment katex.min.css is requested from the Internet, and you cannot set it to a local file.
The question is if we should include it in the package as well and allow for both using the included version, any path, or a path on the internet as at the moment.

BTW, for katex.min.js we do not support a path on the internet at the moment.

[kalvdans]

Yes, at the moment katex.min.css is requested from the Internet, and you cannot set it to a local file.

You can set it to a local file, and that's what I did with the following lines:

html_static_path = ["/usr/share/javascript/katex"]
katex_css_path = "katex.min.css"

Sphinx inserts these html tags in the resulting documentation:

      <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
      <link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
      <link rel="stylesheet" href="_static/katex.min.css" type="text/css" />
      <link rel="stylesheet" href="_static/katex-math.css" type="text/css" />

[hagenw]

Great, that's better than I had expected.

Then the only remaining question is if we should include the CSS file as well with the extension instead of loading it from an external URL. I would vote for staying with the current solution as providing the CSS file via CDN has advanatges over a local file on the server.

Nonetheless, we could think about adding katex.min.css to the extension, and mentioning in the documentation, that the user can switch to the local CSS file by setting katex_css_path = "katex.min.css".

[kalvdans]

I would vote for staying with the current solution as providing the CSS file via CDN has advantages

me too

Nonetheless, we could think about adding katex.min.css to the extension

Then we need to bundle the fonts as well, a total of 2.3 MB data. I'll let you decide.

[hagenw]

OK, as the current package is around 96K, I would vote against bundling the CSS file and fonts with it.

I will close this issue for now.