FR: Can we have the docs in a single page and/or a PDF as well?

[beetleb]

For various health reasons, I often cannot stare at screens for too long.

It would be great if the jj docs also had an option of seeing the whole docs on one page so I can print it out. I'd prefer HTML but PDF will do as well.

If mkdocs has a means to do it (plugin, etc), you can point me to it and I can try building it on my machine myself - but I do think you should consider it for your official docs. I can't be the only one who wants this.

[ilyagr]

I found a plugin that claims to be able to do this at https://github.com/timvink/mkdocs-print-site-plugin . More are listed at https://github.com/mkdocs/catalog?tab=readme-ov-file#-site-conversion-pdfepubetc . I have not yet tried using any of them.

Those plugins might interfere with the mkdocs-material theme we use, but you could try switching to a simpler theme for this. That could break some formatting.

Some other possible channels of support might be https://github.com/mkdocs/mkdocs?tab=readme-ov-file#support and (especially if turning off mkdocs-material messes things up too much) https://github.com/squidfunk/mkdocs-material/discussions

---

I'm not sure this is helpful for you, but FYI, for every jj release, we generate a compressed file with an "offline" version of the docs, for example https://github.com/jj-vcs/jj/releases/download/v0.25.0/jj-v0.25.0-docs-html.tar.gz. That still is composed of many HTML files, but is supposed to be readable offline (on an e-reader maybe?). Unfortunately, I don't think many people have tested how well it works. It's generated like this using the offline plugin.

[ilyagr]

Actually, that mkdocs-print-site-plugin turned out to be pretty fast to setup. Here is the result. Let me know how it works for you; at a glance the result seems like it should be useful.

printed-site.zip

This is for the nightly version of jj. If it's good enough, we might be able to generate this kind of thing automatically.

What I did:

• You need uv installed, e.g. "brew install uv", or see https://jj-vcs.github.io/jj/latest/contributing/#install-uv (or the corresponding page in the archive above, section 26.6.1)
• Clone the jj git repo
• uv add mkdocs-print-site-plugin
• Add print-site at the end of the list of plugins in mkdocs-offline.yml as follows:

diff --git a/mkdocs-offline.yml b/mkdocs-offline.yml
index 058551255e..f8a6d45853 100644
--- a/mkdocs-offline.yml
+++ b/mkdocs-offline.yml
@@ -13,6 +13,7 @@
     - redirects:
         redirect_maps:
             branches.md: bookmarks.md
+    - print-site
 # Turns out the `offline` plugin forces the following
 # option no matter what, and therefore shouldn't be
 # used in the main config file.

• Run uv run mkdocs build -f mkdocs-offline.yml
• Open rendered-docs/print_page.html
• I then did "Save as -> Single page" in Firefox and compressed the result.

[beetleb]

This works perfectly!

Yes, may be a good idea to include it in your regular documentation builds.