two steps to have images end up correctly in _site

[maxandersen]

for now I have to do bundle exec jekyll build && bundle exec rake deploy to have the _site have the actual images.

This works for deployment but using jekyll watch becomes quite annoying since the images are not linked up correctly.

is there a better way ?

[mojavelinux]

Is it because those images are being generated?

[maxandersen]

note, this is in context of using asciidoctor-diagram

[maxandersen]

I think asciidoctor/asciidoctor-diagram#110 and asciidoctor/asciidoctor-diagram#85 shows the issue too.

[maxandersen]

And yes, this is for generated images like asciidoctor-diagram.

[maxandersen]

It seems the core issue is that asciidoc-diagram are not told the actual output path adn cannot generate a relative path to it.

Things works fine if all docs are in the root of the repo, but when using sub-folders the images are now no longer in the right location.

[maxandersen]

example https://github.com/ALMighty/almighty-devdoc which was based on jekyll-asciidoc quickstart but have nested folders to make it really clear.

boarding a plane now - bbl ;)

[maxandersen]

And while on plane I remembered this issue I have hit before. asciidoctor/asciidoctor-diagram#39

So i'm still not sure how to actually best handle this. Seems to be an inherent problem that extensions can't know the relative position they are supposed to generate to.

[maxandersen]

Following the recommendations in asciidoctor/asciidoctor-diagram#39 I added this to my _config.yml:

asciidoctor:
  attributes:
    - idseparator=_
    - source-highlighter=coderay
    - icons=font
    - imagesoutdir=_site

thinking that could make it generate directly into _site but this just results in no images generated at all (at least not that I could see within the jekyll project).

[maxandersen]

Tried:
- imagesdir=_site/diagrams

gives no output at all..

Tried
- imagesdir=diagrams

ends up in _site/../diagrams.

This is definitely following a logic I can currently figure out ;)

[maxandersen]

And finally - it seems when jekyll-asciidoc runs it does not actually set any of the to_dir/out_dir/etc. values so asciidoc-diagram have no chance to read them.

[maxandersen]

in asciidoctor/asciidoctor-diagram#39 its said tools like maven/gradle should set outsdir.

Should jekyll integration not do the same for each doc/page being generated ?

[aslakknutsen]

Adding this hack to get the doc folder https://github.com/ALMighty/almighty-devdoc/blob/master/_plugins/asciidoc.rb#L25 combined with passing that information to Asciidoctor https://github.com/ALMighty/almighty-devdoc/blob/master/_plugins/asciidoc.rb#L79 seems to do the trick.

No imagesdir needed to be set in the Doc itself, but Jekyll is still required to run twice to get the images copied to _site/

[aslakknutsen]

The Jekyll required to run twice issue is 'simply' because on run 1:
Asciidoctor-diagram will generate the images to /sub-path/image.png
On run 2, Jekyll will find these images, think they are just normal assets and copy them to _site/sub-path

Setting imagesoutdir to _site/#{page.dir} when doing the convert call fix this, as it will output directly to the destination folder. But this trigger another interesting problem:

Jekyll's internal lifecycle is: read, generate, render, clean, write
Asciidoctor is called either in generate or render, Diagrams will output the images to the _site folder, the converted asciidoc will be kept in memory by Jekyll. Jekyll will then clean the _site folder and write the converted in memory asciidoc. End result is no images in the _site folder at all.

I'm currently working around that by monkey patching Jekyll to not clean _site at all.

fabric8-services/fabric8-devdoc@4df022d

[aslakknutsen]

So the two last pieces of research to get Asciidoctor-Diagram to work with Jekyll Rake plugins as well can be seen here:

fabric8-services/fabric8-devdoc@75a5113
fabric8-services/fabric8-devdoc@258b2f1

Need to set Asciidoctor in UNSAFE mode to write outside of the doc root due to Jekyll rake plugin setting --destination /tmp/xxxx and only setting outdir in Asciidoctor Jekyll to avoid relative image link issue in html output when splitting outdir into 'target root folder' and image-dir.

[mojavelinux]

I have now overhauled the plugin in preparation to address this issue. I'm now ready for it.

I've already implemented the (Jekyll 3-only) hooks @aslakknutsen uses in ALMighty, so the stage is set. Now I just need to understand what options/attributes I need to assign. Will report back.

[mojavelinux]

This one roasted my brain a bit, but I think I have a couple of strategies that are going to work. Thanks @aslakknutsen for your critical research. That saved me a lot of time...esp the heads up about the site cleaner.

If we set the outdir attribute correctly when invoking Asciidoctor, then Asciidoctor Diagram actually does the right thing. We'll be able to support the option of a single images folder for all pages or an images folder per collection/nested folder. I'll provide more details when I have the PR ready to push.

[mojavelinux]

Btw, I think you can avoid the cleanup monkeypatch by setting the keep_files config setting to all files.

keep_files: [images]

Unfortunately, it only works for a known directory or file, so you can't just say keep everything.

[mojavelinux]

I'm happy to report that this issue is finally resolved and will be part of the upcoming 2.0.0 release!

Information about the new configuration options can be found in the README. See https://github.com/asciidoctor/jekyll-asciidoc#generated-image-location

The simplest configuration is as follows:

asciidoctor:
  base_dir: :docdir
  safe: :unsafe
  attributes:
    - imagesdir=/images

In this case, the imagesoutdir is automatically configured since the imagesdir is relative to the site root. Alternatively, you may specify the imagesoutdir explicitly:

asciidoctor:
  base_dir: :docdir
  safe: :unsafe
  attributes:
    - imagesdir=/images
    - imagesoutdir={site-destination}/images

In both cases, all images end up (and are expected to be in) a single folder.

If you want images to be relative to the document, then set the imagesdir to a relative path.

asciidoctor:
  base_dir: :docdir
  safe: :unsafe
  attributes:
    - imagesdir=images

Of course, if you use a trailing @ to any attribute value, you can override it per document.

I have sent a pull request to almighty-devdoc with these changes. In the PR, the first example from above is enabled. The rest are in comments.

[aslakknutsen]

Excellent! Thank you @mojavelinux

[mojavelinux]

@aslakknutsen Thank you for sharing your fork/prototype. That proved to be very useful while implementing this change and catching some other aspects I had previously missed.