Trouble with MathJax & render_js

[briantoby]

I recently started converting a set of messy .HTML files to MarkDown and am using MkDocs to build the web pages. Works great. I just tried using mkdocs-to-pdf to convert everything to .pdf and that is also just amazing too, but not without some glitches. The first of these is pretty serious to me, as there is math content that if not included leaves the text pretty useless. The remaining two I can live with, but mention in case they are easily addressed.

• I can't get any of my MathJax content to be rendered. I have attached my .yml file here and the output from mkdocs (I'm running this on GitHub actions) is below. There is an error that appears to be from the equation rendering process, but I can't make any sense of it. The MD content is all at https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/tree/main/MDhelp, FWIW.

• The pagination is a bit weird. I expect to see a new page for every web page, but the placement of page breaks seems pretty random. There are a number of places where page breaks are inserted in the .pdf that leave only a few lines of text on the page. In the worst case, a single .html file that should probably fit on <1.5 pages, is spread out over 4 pages: 4 lines of text on the 1st, 1 line on the 2nd, 7 lines on the 3rd and the remainder on the 4th.

• I'm not getting exclude_pages to work. The page I want to exclude is still included.

mkdocs.yml.txt

GitHub Actions output:

Run cd MDhelp
  cd MDhelp
  mv mkdocs.yml_pdf mkdocs.yml
  #mkdocs build
  ENABLE_PDF_EXPORT=1 mkdocs build
  # mv site/GSASII-help.pdf ...
  #cp -vr site ../help_test
  shell: /usr/bin/bash -e {0}
  env:
    pythonLocation: /opt/hostedtoolcache/Python/3.13.5/x64
    LD_LIBRARY_PATH: /opt/hostedtoolcache/Python/3.13.5/x64/lib
  
INFO    -  mkdocs_static_i18n: Building 'en' documentation to directory: /home/runner/work/GSAS-II-tutorials/GSAS-II-tutorials/MDhelp/site
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/runner/work/GSAS-II-tutorials/GSAS-II-tutorials/MDhelp/site
INFO    -  Number headings up to level 3.
INFO    -  Generate a table of contents up to heading level 2.
INFO    -  Generate a cover page with "default_cover.html.j2".
INFO    -  Converting <img> alignment(workaround).
INFO    -  Rendering on `Headless Chrome`(execute JS).
[2173:2200:0721/161553.553233:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161553.553520:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161553.553541:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161553.553555:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161554.842724:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161557.370788:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161600.947918:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2173:0721/161601.010987:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2200:0721/161601.011075:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2200:0721/161601.011094:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161601.012108:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2173:0721/161601.123756:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2173:0721/161601.123866:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2200:0721/161601.123902:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2269:0721/161601.125126:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.Properties.Get: object_path= /org/freedesktop/UPower: org.freedesktop.DBus.Error.ServiceUnknown: The name org.freedesktop.UPower was not provided by any .service files
[2173:2269:0721/161601.125358:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.UPower.GetDisplayDevice: object_path= /org/freedesktop/UPower: org.freedesktop.DBus.Error.ServiceUnknown: The name org.freedesktop.UPower was not provided by any .service files
[2173:2269:0721/161601.125624:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.UPower.EnumerateDevices: object_path= /org/freedesktop/UPower: org.freedesktop.DBus.Error.ServiceUnknown: The name org.freedesktop.UPower was not provided by any .service files
[2173:2173:0721/161601.151551:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2190:0721/161605.850681:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161606.043339:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2190:0721/161606.043448:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161606.051466:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2190:0721/161606.051540:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161606.053478:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2190:0721/161606.053594:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161606.060279:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2190:0721/161606.060357:ERROR:dbus/bus.cc:408] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix")
[2173:2173:0721/161606.106212:ERROR:dbus/object_proxy.cc:590] Failed to call method: org.freedesktop.DBus.NameHasOwner: object_path= /org/freedesktop/DBus: unknown error type: 
[2173:2200:0721/161608.831921:ERROR:google_apis/gcm/engine/mcs_client.cc:700]   Error code: 401  Error message: Authentication Failed: wrong_secret
[2173:2200:0721/161608.831942:ERROR:google_apis/gcm/engine/mcs_client.cc:702] Failed to log in to GCM, resetting connection.
[2173:2200:0721/161608.835549:ERROR:google_apis/gcm/engine/registration_request.cc:291] Registration response error message: DEPRECATED_ENDPOINT
INFO    -  Rendering for PDF.
INFO    -  Output a PDF to "/home/runner/work/GSAS-II-tutorials/GSAS-II-tutorials/MDhelp/site/GSASII-help.pdf".
INFO    -  Converting 41 articles to PDF took 43.6s
INFO    -  Documentation built in 44.27 seconds

[domWalters]

Hi,

The mathjax problem could be related to this:

#82

Are you on Ubuntu using a chromium installed with snap?

I might be able to push a fix for that issue this evening if it is that.

[briantoby]

No, I used the natively installed chromium in /usr/local. Since I submitted the Issue, I found and tried the diagnostic recommended somewhere:

/usr/bin/chromium-browser --headless --disable-gpu --dump-dom https://google.com/

This produces an error message:

[2589:2589:0721/181854.871525:FATAL:content/browser/zygote_host/zygote_host_impl_linux.cc:132] No usable 
sandbox! If you are running on Ubuntu 23.10+ or another Linux distro that has disabled unprivileged user namespaces 
with AppArmor, see https://chromium.googlesource.com/chromium/src/+/main/docs/security/apparmor-userns-restrictions.md. 
Otherwise see https://chromium.googlesource.com/chromium/src/+/main/docs/linux/suid_sandbox_development.md
 for more information on developing with the (older) SUID sandbox. If you want to live dangerously and need an
 immediate workaround, you can try using --no-sandbox.

I then tried adding --no-sandbox to the command line. I then saw many of the error messages above in the original message but the command did seem to run. Is there a way to configure how the headless_chrome_path image gets run? I also tried using to install chrome using browser-actions/setup-chrome@v1 to install it. No different than /usr/bin

I have never used snap for installation on a GitHub runner, but assuming it is allowed, I could do that.

FWIW, I also tried the ReLaXed JS renderer too and also saw the sandbox error.

If you did push a fix, I'd need to install from GitHub into mkdocs -- not sure how to do that. I have only used pip.

[sebascert]

I can confirm that installing google chrome via .deb works in my local machine (Ubuntu 24.04.2), here is a repo showing how to install headless chrome via .deb for github action,
this will probably fix your issue

[briantoby]

That was really helpful, in that I was able to install chrome and run it headless w/o the --no-sandbox added, but I still get many (though fewer) "Failed to..." warning messages as before (if they matter?) but do not see any equations in my .pdf.

Bit from web page:

Same section from PDF:

[briantoby]

I have to retract some of what is above. I am seeing some of the MathJax content, but am also missing a lot.

Most of the display equations are missing, but I do see many of the in-line equations:

HTML:

PDF:

But at least one of the display equations did get rendered:

HTML:

PDF:

[sebascert]

Can you please send a link to the markdown source which renders to the images you just sent?

[sebascert]

I have a similar problem to you, posted on #85, In my case only the block equations are rendered, every inline equation is not. I'm using this extension as mentioned in this guide:

markdown_extensions:
  - pymdownx.arithmatex:
      generic: true
      tex_inline_wrap: ["$", "$"]
      tex_block_wrap: ["$$", "$$"]

[briantoby]

Can you please send a link to the markdown source which renders to the images you just sent?

The markdown source is in https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/tree/main/MDhelp

The workflow script is in https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/blob/main/.github/workflows/mkdocs_pdf.yml. (output here: https://github.com/AdvancedPhotonSource/GSAS-II-tutorials/actions/runs/16428974586/job/46426182956) Note that it renames file mkdocs.yml_pdf to mkdocs.yml

The snippets above came from files cluster.md, phasetexture.md and phasepeaks.md

[sebascert]

I think It may be because you need the config I posted in the previous comment, the block equations on the $$ format may not be recognized by mathjax, maybe try pymdownx.arithmatex following the guide I listed.

[briantoby]

I made the change you suggested, replacing

  - mdx_math

with

  - pymdownx.arithmatex:
      generic: true
      tex_inline_wrap: ["$", "$"]
      tex_block_wrap: ["$$", "$$"]

in the markdown_extensions. and changed

#extra_javascript: 
#  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML

to

extra_javascript:
  - javascripts/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

and added the docs/javascripts/mathjax.js file. Now both my .html files and .pdf file show all equations as TeX strings surrounded by $$...$$ or $...$, rather than being formatted as equations. Noting that the inline equations are in my .md files with delimiters \(...\) that get converted to $...$, this seems to tell me that they are getting recognized.

I'm clearly doing something wrong, but it is not yet clear to me what that is. Investigating.

[domWalters]

Hey,

Can you try this branch, with the new pdf_engine setting:

https://github.com/domWalters/mkdocs-to-pdf/tree/impl-playwright-pdf-engine

to-pdf:
  pdf_engine: chromium
  render_js: true
  headless_chrome_path: /path/to/chromium

This was contributed a while ago by @hkato but I haven't merged it yet.

I've been having real issues getting weasyprint to work on my new desktop OS, which is why I've not done much on this repo the last few months, so thought I'd try it.

I just pasted your cluster.md source and ran the build and it looked good to me at a glance.

[domWalters]

You can see some example MathJax rendered here:

https://mkdocs-to-pdf.readthedocs.io/en/impl-playwright-pdf-engine/examples/mathjax/

[sebascert]

I have this same problem, which I explained in more detail in #85 (might also consider closing it as duplicate), and using the impl-playwright-pdf-engine branch makes no difference

mkdocs-to--pdf config

  - to-pdf:
      pdf_engine: chromium
      enabled: !ENV [MKDOCS_ENABLE_TO_PDF, False]
      render_js: true
      headless_chrome_path: !ENV MKDOCS_TO_PDF_CHROME_PATH # /usr/bin/google-chrome

mkdocs build output

$ mkdocs build
INFO    -  git-committers plugin DISABLED
INFO    -  [macros] - No default module `main` found
INFO    -  git-committers: loading authors cache file
INFO    -  git-committers: saving authors cache file
INFO    -  [macros] - Config variables: ['extra', 'config',
           'environment', 'plugin', 'git', 'analytics', 'macros', 'filters',
           'filters_builtin']
INFO    -  [macros] - Config macros: ['context', 'macros_info', 'now',
           'fix_url']
INFO    -  [macros] - Config filters: ['pretty', 'relative_url']
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory:
           /home/yoaquin/projects/cp-algorithms/public
INFO    -  Doc file 'algebra/discrete-log.md' contains a link
           'phi-function.md#toc-tgt-2', but the doc 'algebra/phi-function.md'
           does not contain an anchor '#toc-tgt-2'.
INFO    -  Number headings up to level 3.
INFO    -  Generate a table of contents up to heading level 2.
INFO    -  Generate a cover page with "default_cover.html.j2".
INFO    -  Converting <img> alignment(workaround).
INFO    -  Rendering JavaScript using Playwright/Chromium
INFO    -  Rendering for PDF.
INFO    -  Output a PDF to
           "/home/yoaquin/projects/cp-algorithms/public/pdf/document.pdf".
INFO    -  Rendering PDF using Playwright/Chromium
INFO    -  Converting 166 articles to PDF took 132.9s
INFO    -  Documentation built in 154.38 seconds

Version of mkdocs-to-pdf used:

$ pip freeze | grep pdf
mkdocs-to-pdf @ git+https://github.com/domWalters/mkdocs-to-pdf.git@76cc5d2a567a37a77ce86c02b47538d5685b9f9d

$ git log -1 76cc5d2a567a37a77ce86c02b47538d5685b9f9d
commit 76cc5d2a567a37a77ce86c02b47538d5685b9f9d (origin/impl-playwright-pdf-engine)

[briantoby]

@sebascert I think the problem with arithmatex was that I did not install PyMdownx. No error for the lack of it. It required some minor tweaks to MD text (and FWIW I prefer to have all the default delimiters work, so I am not defining tex_inline_wrap), but it worked!. Both the in-line and the display equations work -- at least everywhere I have looked.

The file created is at https://advancedphotonsource.github.io/GSAS-II-tutorials/docs/GSASII-help.pdf

@domWalters I tried out the impl-playwright-pdf-engine but did not see any obvious differences from what was created by the to-pdf version on pypi. FWIW, I'm still getting the funny page breaks, with even some one-line/page in a few places. As one example, the contents of pages 3-6 in the above PDF comes from a very small .md file that really should not be more than 2 pages and I don't see any reason for why page-breaks were inserted at those points where they occur looking at the .md file. If there is something I should try that might eliminate this or even allow for investigation, please let me know. Otherwise, I'm happy to quit with "good enough."

[sebascert]

I tried what you suggested but it didn't work, neither with mkdocs-to-pdf from pypi or playwright-pdf-engine.

$ pip show pymdown-extensions
Name: pymdown-extensions
Version: 10.16
Summary: Extension pack for Python Markdown.
Home-page:
Author:
Author-email: Isaac Muse <Isaac.Muse@gmail.com>
License:
Location: /home/yoaquin/projects/cp-algorithms/.pyvenv/lib/python3.12/site-packages
Requires: markdown, pyyaml
Required-by: mkdocs-material