Specify the path to generated files for the HTML src attribute.

[bwklein]

I think the section in the code related to this issue is: https://github.com/asciidoctor/asciidoctor-mathematical/blob/d82041ddce64ea6014f3f3d613f3d5e6c4d257d3/lib/asciidoctor-mathematical/extension.rb#L202

Here is some frontmatter I have set up now in a file.

ifdef::backend-pdf[]
:imagesdir: /builds/tecidev/support/static/images
:imagesoutdir: /builds/tecidev/support/static/images
endif::[]
ifdef::backend-html5s[]
:imagesdir: /images
:imagesoutdir: /images
endif::[]

The PDF backend writes images to the correct location and reads images from the same location. No problem there.

The HTML backend is where the problem appears. If I set imagesoutdir to the absolute path of /builds/tecidev/support/static/images as I do for the PDF backend, which is where I want them to go, then they will write there no problem, but then the src path in the HTML for that image is src="/builds/tecidev/support/static/images/stem-hash.svg" instead of src="/images/stem-hash.svg" which is what I would expect it to be based on my imagesdir attribute.

Currently, in the HTML backend, I set both the imagesdir and imagesoutdir to /images so that the path is correct in the HTML src attribute, but the images the HTML is pointing to were actually created by the PDF backend process. The HTML process writes them to the 'images' folder in the root of my project that I just .gitignore and delete from time to time. The unwanted byproduct of a broken process. 😢

It seems that we need a way to specify where the file should write to as an absolute path like imagesoutdir, and also specify the file path for the output files relative to the imagesdir attribute. Something like the following would be great.

ifdef::backend-html5s[]
:imagesdir: /images
:imagesoutdir: /builds/tecidev/support/static/images
:imagesoutpath: 
endif::[]

You should default the value of imagesoutpath to be the imagesdir attribute if it isn't defined.

A more complex example where you wanted the generated images to be in a subdirectory of your main images folder would look like this.

ifdef::backend-html5s[]
:imagesdir: /images
:imagesoutdir: /builds/tecidev/support/static/images/gen
:imagesoutpath: gen
endif::[]

In this case the stem SVG image generated for the HTML processor would go to /builds/tecidev/support/static/images/gen and the image src attribute in the output HTML would be /images/gen/stem-hash.svg.

Having said all this, I could totally be missing something and there is a better way to do it all that will solve this issue.

Here is a video tour of the situation. https://www.youtube.com/watch?v=SVezqj6jCww

I thought this would be better than lots of words here so you can see for yourself how things are setup. The project is in a private repo that I am glad to invite people to if they want to pull the site and test it locally, but I can't make it public at this time.

[dalemartin]

@bwklein I think what you need to do is somehow remove -r asciidoctor-mathematical from the options you pass into your asciidoctor_real script (shown at 8:44 of your video) when using html5 backend, but do call it when using the pdf backend. I believe html5 just creates temporary stem image files during generation and cleans them up, so the pdf images don't need to be used at all, and changes to your source shouldn't break your html build without first building the pdfs.

I think because you're calling -r asciidoctor-mathematical while generating html5, it's messing up the image directory attributes and breaking how the html backend handles all images. Without the unneeded call to the math extension, your other (non-stem) images should just function properly.

[dalemartin]

I just did a little testing on my repo to confirm the above works (barring any breaking setup differences in our file tree structures etc.).

I like to use the html backend by calling

# adding -r asciidoctor-mathematical will break html backend build!
asciidoctor \
    -D docs/output-html

and the pdf backend by calling

# I prefer vector graphics (svg) over the default png format
asciidoctor-pdf \
    -a pdf-themesdir=docs/resources/themes \
    -a pdf-theme=mytheme \
    -a pdf-fontsdir=docs/resources/fonts \
    -r asciidoctor-mathematical \
    -a mathematical-format=svg \
    -D docs/output-pdf \
    docs/master-docs/*/*.adoc

So maybe your asciidoctor.sh could look something like:

#!/bin/bash

SOURCE_FILES="path-to-master-docs/*.adoc"

COMMON="
--quiet
--no-header-footer
-a allow-uri-read
--safe-mode=unsafe
-r asciidoctor-bibtex
-r asciidoctor-diagram"

HTML="
-r asciidoctor-html5
-b html5s
$COMMON
-D htm-output-dir
$SOURCE_FILES"

PDF="
-r asciidoctor-pdf
-b pdf
-r asciidoctor-mathematical
-a mathematical-format=svg
$COMMON
-D pdf-output-dir
$SOURCE_FILES"

# HTML build
echo "Building HTML..."
/usr/local/bin/asciidoctor_real $HTML

# PDF build
echo "Building PDFs..."
/usr/local/bin/asciidoctor_real $PDF

echo "Done"

Hope this helps!

[bwklein]

Thank you for your help with this matter. The problem is that I want to use images for equations in my site and not require MathJax to run over the page content after page load. It causes some issues with the content on the page jumping around, especially when navigating to an anchor element on a page. With the images the pages load in quickly and the anchor stays in place at the top of the page without any movement.

[dalemartin]

Ah I see, that's interesting. Thanks for clarifying. I'm not sure if this is a use case it's designed for to be honest, but I'm sure there's a way to make it work. Without knowing anything about MathJax, can it not output PNGs? Maybe there's just a patch needed in the asciidoctor gem to specify that.

[bwklein]

MathJax can output images. The problem is that it doesn't start replacing equation text with images until after the page is loaded. So the page loads, then lines of text start being replaced by images which expands that part of the document. This happens for every equation and the content moves around in the browser.

[dalemartin]

Got it. Maybe asciidoctor-katex would reduce this to an acceptable level for you? I think KaTeX claims it doesn't need to re-flow the page, so even if it doesn't load instantly, the part you first see won't jump around.

[bwklein]

I'll take a look, thank you. I hope that the output looks the same in PDF and HTML.

[dalemartin]

Yeah they use different packages so no guarantee. If asciidoctor-katex leaves image files behind, maybe you could work the other direction and pull those into your PDFs.