asciidoctor-maven-plugin preserveDirectories and images issue

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

asciidoctor-maven-plugin preserveDirectories and images issue

bostandyk
This post was updated on .
Hi,

i have a following directory structure:

src/main/asciidoc
                           index.adoc
src/main/asciidoc/part1
                                      images
                                               1.png
                                       part1.adoc
src/main/asciidoc/part2
                                       images
                                               1.png
                                       part2.adoc

index.adoc contains includes of two another files. Each of these *.adoc files contains link to images like

image::images/1.png[]

but when i run asciidoctor-maven-plugin images are not displayed.

                <configuration>
                    <sourceHighlighter>coderay</sourceHighlighter>
                    <sourcemap>true</sourcemap>
                    <relativeBaseDir>true</relativeBaseDir>
                    <attributes>
                        <icons>font</icons>
                        <sectnums>false</sectnums>
                    </attributes>
                </configuration>
                <executions>
                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <sourceDocumentName>index.adoc</sourceDocumentName>
                            <attributes>
                                <pagenums/>
                                <toc/>
                            </attributes>
                        </configuration>
                    </execution>
                    <execution>
                        <id>asciidoc-to-html</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <preserveDirectories>true</preserveDirectories>
                            <attributes>
                                <sectanchors>true</sectanchors>
                            </attributes>
                        </configuration>
                    </execution>
                </executions>

So, i need to build one .pdf file and set of .html files. Also, each html files contains links "images/images/1.png".

Can you please help me. What should i do with my resources or plugin settings for correct display?

P.S. How i can disable imagesDir option?
                     
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-maven-plugin preserveDirectories and images issue

abelsromero
Welcome to the forums,

First of all, keep in mind that by default images are searched in a directory called "images", so if no "imagesdir" attribute (imagesDir in maven configuration) is set, all images in HTML are prefixed with that. That's why in the part1.adoc and part2.adoc, you get "images/images/1.png" when using "image::images/1.png[] ".
If you set imagesdir to something like "my-path" and use "image::1.png[] ", you'll get "my-path/1.png".

Now, on the build, I understand you want 3 outputs:
1. The PDF document
2. index.html with the embedded included documents and proper images references.
3. part1.html and part2.html as stand-alone documents with proper images references.
All of this, using the same source documents.

Keep in mind, those are very different use cases and the current structure is not simple.
Having images inside each directory is very convenient if you're using some preview in tools like Atom or IntelliJ, but a preview and final render not always are compatible. Unless you'r really only dropping stand alone documents in a directory structure, I'd recommend keeping all images inside a root structure, that of course affects the previews.

Said that, I could achieve something close using three maven executions and some changes. But I am not sure that's 100%  what you wanted.

What I did was:
1. Create a "images" directory in my root -> "src/docs/asciidoc" and put all images inside.
2. Referece images in all documents simply by name "image::1.png[]". Remember, that by default imagesdir = "images".
3. Setup the following three executions. Note that:
    - I used <resources> to exclude things i don't want in the target directory, but that's not mandatory.
    - No <imagesDir> is used.
    - The third configuration renders part1 and part2 uses <preserveDirectory> default value "false" to render the files in the root of the output directory.
   - I just noticed that third configuration also renders index.html.
            <executions>
                    <execution>
                        <id>generate-pdf-doc</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>pdf</backend>
                            <sourceDocumentName>index.adoc</sourceDocumentName>
                            <resources>
                                <resource>
                                    <directory>src/docs/asciidoc</directory>
                                    <excludes>
                                        <exclude>part*</exclude>
                                        <exclude>images</exclude>
                                        <exclude>images/*.*</exclude>
                                    </excludes>
                                </resource>
                            </resources>
                            <outputDirectory>${build.directory}/generated-docs/pdf</outputDirectory>
                        </configuration>
                    </execution>
                    <execution>
                        <id>asciidoc-to-html-index</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <sourceDocumentName>index.adoc</sourceDocumentName>
                            <outputDirectory>${build.directory}/generated-docs/html-index</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>src/docs/asciidoc</directory>
                                    <excludes>
                                        <exclude>part*</exclude>
                                    </excludes>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                    <execution>
                        <id>asciidoc-to-html-parts</id>
                        <phase>generate-resources</phase>
                        <goals>
                            <goal>process-asciidoc</goal>
                        </goals>
                        <configuration>
                            <backend>html5</backend>
                            <outputDirectory>${build.directory}/generated-docs/html-parts</outputDirectory>
                            <resources>
                                <resource>
                                    <directory>src/docs/asciidoc</directory>
                                    <excludes>
                                        <exclude>part*</exclude>
                                    </excludes>
                                </resource>
                            </resources>
                        </configuration>
                    </execution>
                </executions>
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-maven-plugin preserveDirectories and images issue

mojavelinux
Administrator

On Tue, Apr 4, 2017 at 8:27 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Keep in mind, those are very different use cases and the current structure is not simple.
Having images inside each directory is very convenient if you're using some preview in tools like Atom or IntelliJ, but a preview and final render not always are compatible. Unless you'r really only dropping stand alone documents in a directory structure, I'd recommend keeping all images inside a root structure, that of course affects the previews.

Very well said.

The way I like to define the imagesdir location is the "images catalog". If you think of it that way, and think of the image target as the location relative to this catalog, everything becomes a lot simpler.

Getting the image to work in previews is actually easy. You just set imagesdir in the document to the relative path from the document to the images catalog. Your build can then override this value if necessary to be a different path. As long as the image target is relative to this location, the path will always work.

It's possible to organize your file structure in other ways, but then you add quite a lot of burden on yourself to get the configuration to work. As Abel pointed out, it's not really a limitation of Asciidoctor. You are asking the software to do vastly different things for different scenarios...and it's the logic that gets complicated.

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: asciidoctor-maven-plugin preserveDirectories and images issue

mojavelinux
Administrator
In reply to this post by abelsromero

On Thu, Apr 6, 2017 at 7:24 PM, Dan Allen <[hidden email]> wrote:
As long as the image target is relative to this location, the path will always work.

By "image target", I mean the target value in the image macro.


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux