Generating absolute URLs for images with awestruct

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Generating absolute URLs for images with awestruct

xcoulon
Hello and happy new year !

This question is a follow up for http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-td528.html

Here's our use-case for our upcoming website baked with awestruct:
- we have blog posts written in asciidoc in /blog
- these blog posts are also tagged and thus can be browsed by tags , in pages such as /blog/tag/jbds/ for example (those page display the content of the blog posts, not just their titles)
- we deploy the staging website on gh-pages, which means that there's a deployment context which is not ROOT, but the name of the github repo (for instance, http://jbosstools.github.io/jbosstools-website).

This leads me to the following question (or request): how can we ask asciidoctor to generate absolute URLs for images, so that they work in all cases ? In our case, relative locations work for each blog post, but not when browsed by tags.

Thanks in advance
Best regards,
Xavier
Reply | Threaded
Open this post in threaded view
|

Re: Generating absolute URLs for images with awestruct

mojavelinux
Administrator

On Fri, Jan 3, 2014 at 8:57 AM, xcoulon [via Asciidoctor :: Discussion] <[hidden email]> wrote:
how can we ask asciidoctor to generate absolute URLs for images, so that they work in all cases ? In our case, relative locations work for each blog post, but not when browsed by tags.

There are a number of solutions to this problem. I'll suggest the one I recommend.

My strongest recommendation is to set the imagesdir attribute on the Asciidoctor configuration in _site/config.yml to the location of the images directory as a root web path.

[source,yaml]
----
asciidoctor:
  :attributes:
    imagesdir: /images
----

This approach requires that you place all images under the /images path. You could create a subdirectory named "posts" for all images related to posts. Then, in your AsciiDoc source, you'd put:

[source,asciidoc]
----
image::post/name-of-screenshot.png[Screenshot]
----

In order for the image to work in a preview window or on GitHub (i.e. outside of Awestruct), you'll need to add the following attribute to the header of the document:

[source,asciidoc]
----
:imagesdir: ../images
----

If you want to have your images alongside posts, it's a bit trickier. You might need to use an Awestruct extension to set the imagesdir dynamically based on which file you are processing.

The important thing to remember is that the target of an image macro should always be relative. That gives you the flexibility of controlling the path by alternating the imagesdir attribute, either site-wide or per page.

-Dan

p.s. Image paths are also affected by the indexifier extension, which turns /about.html into /about/index.html