setting imagesdir for asciidoc articles baked with awestruct

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

setting imagesdir for asciidoc articles baked with awestruct

xcoulon
hello !

I have an asciidoc article in an awestruct-baked site.
This article starts with the following content (including the fron matter):

---
layout: blog
tags: [jbosstools, jbds, mobile]
---
= JBoss Tools 4.1 and Red Hat JBoss Developer Studio 7 go GA
author
:imagesdir: blog/images
...
image::open-with-livereload.png[]
...

In the generated HTML page, I have the followin img tag:
<img alt="open with livereload" src="/images/open-with-livereload.png"> </img>

It seems like the :imagesdir: property defined at the top of the asciidoc part was not taken into account.

How can I specify that value ?

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

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Or is there a way to *unset* the default '/images' value for the :imagesdir: property in the asciidoc article ?

Thanks
Xavier
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

LightGuardjp
This is for awestruct, right? Try the :awestruct-imagesdir: variable in the document header. 

Sent from Mailbox for iPhone


On Tue, Aug 27, 2013 at 5:08 AM, xcoulon [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Or is there a way to *unset* the default '/images' value for the :imagesdir: property in the asciidoc article ?

Thanks
Xavier


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p529.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Hi Jason

Thanks for your reply, I'll try that solution.

Yesterday, I found a workaround by creating a custom extension which extends the Posts class:

module Awestruct
  module Extensions
    class MyPosts < Posts

      def initialize(path_prefix='', assign_to=:posts, archive_template=nil, archive_path=nil, opts={})
        super(path_prefix, assign_to, archive_template, archive_path, opts)
        @imagesdir = opts[:imagesdir] || '/images'
        puts "Initialized MyPosts extension with imagesdir=" + @imagesdir
      end
     
      def execute(site)
        super(site)
        site.posts.each do |page|
          page.imagesdir = site.base_url + @imagesdir
        end
      end
    end
  end
end


This is convenient because the imagesdir property is configured in the pipeline.rb for all the blog posts, so this does not need to be configured in each article.

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

Re: setting imagesdir for asciidoc articles baked with awestruct

mojavelinux
Administrator
Xavier,

The solution you came up with certainly works, and for parts of the integration that approach will be the only solution. Fortunately, as of 0.1.4.rc.1, Asciidoctor accommodates the use case you present here.

The topic at hand is the precedence of attribute assignment. By default, the precedence, from highest to lowest is as follows:

- Attribute passed to the API or CLI
- Attribute defined in the document
- Intrinsic attribute value (default values)

The intrinsic value for the imagesdir attribute is empty string. If the attribute is defined no where else, then the value from the document is honored. However, we do define it somewhere else.

Awestruct defines a set of default attributes that it passes to the API (see https://github.com/awestruct/awestruct/blob/master/lib/awestruct/config/default-site.yml). One of the attributes in that configuration is imagesdir. The value there is set to '/images'. That means the value in your document is skipped due to the precedence rules.

Fortunately, there is one additional place you can override the attribute. This gives you the opportunity to set your own default and to flip the precedence order so that the document wins out. Let's talk about how to change the precedence first.

If an attribute value that is passed to the API or CLI ends with an '@' symbol, it makes that assignment have a lower precedence than an assignment in the document. Let's add that to the precedence list defined earlier.

- Attribute passed to the API or CLI that does not end in '@'
- Attribute defined in the document
- Attribute passed to the API or CLI that ends in '@'
- Intrinsic attribute value (default values)

You can define attributes you want to pass to the API in the _config/site.yml file. Here's an example entry for Asciidoctor (inside the fenced code blocks):

```yaml
asciidoctor:
  :safe: safe
  :attributes:
    imagesdir: /assets/images@
    icons: font
    ...
```

NOTE: The second-level keys (safe and attributes, in this case) must have colons on both sides of the key name. The rest of the keys only have a colon after the key.

With this configuration added, you should observe that the imagesdir attribute in your document is now respected.

In closing, I want to mention something about the imagesdir setting in your document. Generally I like to set it to a value that makes images appear on GitHub. Then, I use Awestruct to override that value when building the site. It's up to you how you do it, but just keep that in mind.

Cheers,

-Dan


On Wed, Aug 28, 2013 at 2:29 AM, xcoulon [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi Jason

Thanks for your reply, I'll try that solution.

Yesterday, I found a workaround by creating a custom extension which extends the Posts class:

module Awestruct
  module Extensions
    class MyPosts < Posts

      def initialize(path_prefix='', assign_to=:posts, archive_template=nil, archive_path=nil, opts={})
        super(path_prefix, assign_to, archive_template, archive_path, opts)
        @imagesdir = opts[:imagesdir] || '/images'
        puts "Initialized MyPosts extension with imagesdir=" + @imagesdir
      end
     
      def execute(site)
        super(site)
        site.posts.each do |page|
          page.imagesdir = site.base_url + @imagesdir
        end
      end
    end
  end
end


This is convenient because the imagesdir property is configured in the pipeline.rb for all the blog posts, so this does not need to be configured in each article.

Best regards,


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p531.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Hi Dan !

Sorry, I'm a bit late on this thread.
Thanks for the long explanation, but I can't get it working with awestruct-0.5.4.rc2 with asciidoctor-0.1.4.

No matter what I put in the document header or in a custom extension, the value defined in _config/site.yml is still used, even though I suffixed it with '@' as you suggested.

Here's what I have now:
- in _site/config.yml:
---
asciidoctor:
  :safe: safe
  :attributes:
    imagesdir: /images@
    icons: font
---

- in my adoc file:
---
:awestruct-imagesdir: /features
...
image::images/features-openshift-applicationwizard-reduced.png[OpenShift Application Wizard]
---

in a custom awestruct extension, I specify the 'page.imagesdir' value by setting something like 'http://localhost:4242/features'

At the end of the build, the generated HTML for the images is something like:
<img src="/images/images/features-openshift-applicationwizard-reduced.png" alt="OpenShift Application Wizard">

The generated path starts with '/images/images/..', which means that the default imagesdir value from _config/site.yml was used.
Ideally, I would like to have an absolute path because the site currently deployed on github, so I need to preprend the site context (which is configured in my staging profile). This is why I was hoping to have the custom extension working.
Note: this works fine with awestruct-0.5.3 but we need to migrate to a more recent version because some users run it on MacOSX Mavericks.

I like very much the idea that a relative path should be used with awestruct while still letting github render the page and display the images, which is why I'm trying to find the right configuration.

Thanks.
Xavier

Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

LightGuardjp
There's the base_url in config.yml you could set per environment and use that in the src for the image. Interpolation in asciidoctor files doesn't work in 0.5.3, but does in 0.5.4.rc or higher.

I think you should be able to get what you need with those things and with what you've already tried. If not, please follow-up.


On Thu, Nov 21, 2013 at 3:36 AM, xcoulon [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi Dan !

Sorry, I'm a bit late on this thread.
Thanks for the long explanation, but I can't get it working with awestruct-0.5.4.rc2 with asciidoctor-0.1.4.

No matter what I put in the document header or in a custom extension, the value defined in _config/site.yml is still used, even though I suffixed it with '@' as you suggested.

Here's what I have now:
- in _site/config.yml:
---
asciidoctor:
  :safe: safe
  :attributes:
    imagesdir: /images@
    icons: font
---

- in my adoc file:
---
:awestruct-imagesdir: /features
...
image::images/features-openshift-applicationwizard-reduced.png[OpenShift Application Wizard]
---

in a custom awestruct extension, I specify the 'page.imagesdir' value by setting something like 'http://localhost:4242/features'

At the end of the build, the generated HTML for the images is something like:
<img src="/images/images/features-openshift-applicationwizard-reduced.png" alt="OpenShift Application Wizard">

The generated path starts with '/images/images/..', which means that the default imagesdir value from _config/site.yml was used.
Ideally, I would like to have an absolute path because the site currently deployed on github, so I need to preprend the site context (which is configured in my staging profile). This is why I was hoping to have the custom extension working.
Note: this works fine with awestruct-0.5.3 but we need to migrate to a more recent version because some users run it on MacOSX Mavericks.

I like very much the idea that a relative path should be used with awestruct while still letting github render the page and display the images, which is why I'm trying to find the right configuration.

Thanks.
Xavier




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p1035.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Hi Jason and thanks for your reply.

My current plan was that each folder in my website has its own ./images subfolders. This means that using the site.base_url does not fully satisfy my requirements.
I'm already using it in a custom extension that worked in 0.5.3 but not in 0.5.4.rc2, sadly.
You can take a look at the code on github: https://github.com/xcoulon/jbosstools-website/

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

Re: setting imagesdir for asciidoc articles baked with awestruct

mojavelinux
Administrator
In reply to this post by xcoulon
Xavier,

You almost have it right. The problem is that you aren't using the correct attribute name in your AsciiDoc file. Instead of:

[source,asciidoc]
--
:awestruct-imagesdir: /features
--

you should have:

[source,asciidoc]
--
:imagesdir: /features
--

The imagesdir attribute is a native AsciiDoc attribute, not a special Awestruct attribute. The only time you prefix the attribute name with "awestruct-" (or "page-") is when you need to set a property on the Awestruct Page object.

See if that works for you. Then we can go from there.

-Dan



On Thu, Nov 21, 2013 at 3:35 AM, xcoulon [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi Dan !

Sorry, I'm a bit late on this thread.
Thanks for the long explanation, but I can't get it working with awestruct-0.5.4.rc2 with asciidoctor-0.1.4.

No matter what I put in the document header or in a custom extension, the value defined in _config/site.yml is still used, even though I suffixed it with '@' as you suggested.

Here's what I have now:
- in _site/config.yml:
---
asciidoctor:
  :safe: safe
  :attributes:
    imagesdir: /images@
    icons: font
---

- in my adoc file:
---
:awestruct-imagesdir: /features
...
image::images/features-openshift-applicationwizard-reduced.png[OpenShift Application Wizard]
---

in a custom awestruct extension, I specify the 'page.imagesdir' value by setting something like 'http://localhost:4242/features'

At the end of the build, the generated HTML for the images is something like:
<img src="/images/images/features-openshift-applicationwizard-reduced.png" alt="OpenShift Application Wizard">

The generated path starts with '/images/images/..', which means that the default imagesdir value from _config/site.yml was used.
Ideally, I would like to have an absolute path because the site currently deployed on github, so I need to preprend the site context (which is configured in my staging profile). This is why I was hoping to have the custom extension working.
Note: this works fine with awestruct-0.5.3 but we need to migrate to a more recent version because some users run it on MacOSX Mavericks.

I like very much the idea that a relative path should be used with awestruct while still letting github render the page and display the images, which is why I'm trying to find the right configuration.

Thanks.
Xavier




If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p1035.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
hi Dan !

Thanks for your reply !

I now understand that something like
[source]
----
:awestruct-imagesdir:/features
----

is an helper to provide custom value back to that page object if I need to interact with the document layout.

The confusing part is that as I'm following your suggestion, the generated path to images is still the same
[source]
----
<img src="/images/images/mypicture.png">
----

I even removed the default settings in the _config/site.yml to make sure nothing interferes.
I just pushed my changes on http://github.com/xcoulon/jbosstools-website with commit aa8bacd if you want to get a look at it.
There must be something wrong in my code, but I can't see where :-/

Thanks
Best regards,
Xavier

Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Hello,

Just to keep you posted, I found the solution to my problem, thanks to the hints I got in previous replies.

It turns out that I just needed to set the following config (in _site/config.yml):
asciidoctor:  
  :safe: safe
  :attributes:
    imagesdir: .
    icons: font

and then use the following syntax in my .adoc files:
image::images/whatever.png

assuming that the images are in a subfolder of the current document.
Even cooler, it works both when building our site with awestruct and when looking at the document rendered in HTML on github \o/

Again, thanks for your help!

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

Re: setting imagesdir for asciidoc articles baked with awestruct

mojavelinux
Administrator

Xavier,

You've got it! That explanation is spot on.

I'll clarify that the awestruct-* attributes are only used to define a limited set of what Awestruct recognizes, and it's not correlated with Asciidoctor rendering behavior. It's more about the layout & handling of the page. You typically only use that syntax to set the following:

* awestruct-layout
* awestruct-tags (for the blog)
* awestruct-javascripts (requires custom logic in main template)

Also, the awestruct- prefix is deprecated in favor of page- for these attributes.

To configure AsciiDoc output globally, you define attributes in _config/site.yml as you have discovered.

I look forward to checking out your new site!

Cheers,

Dan

On Dec 3, 2013 10:25 AM, "xcoulon [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
Hello,

Just to keep you posted, I found the solution to my problem, thanks to the hints I got in previous replies.

It turns out that I just needed to set the following config (in _site/config.yml):
asciidoctor:  
  :safe: safe
  :attributes:
    imagesdir: .
    icons: font

and then use the following syntax in my .adoc files:
image::images/whatever.png

assuming that the images are in a subfolder of the current document.
Even cooler, it works both when building our site with awestruct and when looking at the document rendered in HTML on github \o/

Again, thanks for your help!

Best regards,
Xavier


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p1173.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

mojavelinux
Administrator
In reply to this post by xcoulon

I just thought of a better way to explain the page-* attributes. The page-* attributes are for passing information up to Awestruct. Attributes such as imagesdir are for passing information down to Asciidoctor.

I recognize that a table to explain this would be nice to have. I think we'll add a section to the Asciidoctor user manual to explain this integration.

-Dan

On Dec 3, 2013 10:47 AM, "Dan Allen" <[hidden email]> wrote:

Xavier,

You've got it! That explanation is spot on.

I'll clarify that the awestruct-* attributes are only used to define a limited set of what Awestruct recognizes, and it's not correlated with Asciidoctor rendering behavior. It's more about the layout & handling of the page. You typically only use that syntax to set the following:

* awestruct-layout
* awestruct-tags (for the blog)
* awestruct-javascripts (requires custom logic in main template)

Also, the awestruct- prefix is deprecated in favor of page- for these attributes.

To configure AsciiDoc output globally, you define attributes in _config/site.yml as you have discovered.

I look forward to checking out your new site!

Cheers,

Dan

On Dec 3, 2013 10:25 AM, "xcoulon [via Asciidoctor :: Discussion]" <[hidden email]> wrote:
Hello,

Just to keep you posted, I found the solution to my problem, thanks to the hints I got in previous replies.

It turns out that I just needed to set the following config (in _site/config.yml):
asciidoctor:  
  :safe: safe
  :attributes:
    imagesdir: .
    icons: font

and then use the following syntax in my .adoc files:
image::images/whatever.png

assuming that the images are in a subfolder of the current document.
Even cooler, it works both when building our site with awestruct and when looking at the document rendered in HTML on github \o/

Again, thanks for your help!

Best regards,
Xavier


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/setting-imagesdir-for-asciidoc-articles-baked-with-awestruct-tp528p1173.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Reply | Threaded
Open this post in threaded view
|

Re: setting imagesdir for asciidoc articles baked with awestruct

xcoulon
Hi Dan !

yes, "page-" prefix looks more generic and not bound to awestruct ;-)
and yes, I can use it to pass attributes back to awestruct (including custom extensions). This is really powerful.
I think the trick is just to understand that awestruct can configure asciidoctor and any asciidoctor document can provide awestruct with custom attributes.

Best regards,
Xavier