.asciidoctorconfig

[rdmueller]

When I work with included subdocuments, I often face the problem that the preview can't find my images. This is because I set the :imagesdir: in the main .adoc-File and the included document can't give the preview a hint about this.

A nice solution can be found here: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html

A file called .asciidoctorconfig which will be prepended for the preview. This gives you the chance to tell the preview about the correct imagesdir and all images will be displayed.

[bovinemagnet]

I like this idea, however, can I ask how this is different from including a _attributes.adoc file, as this seems to be the common way to do this (I know it is troublesome).

I like it, because it might solve the issue I have with my workflow, which is, I edit with vs-code using asciidoctor-vscode , and publish with Antora, and asciidoc-pdf.

The two things that stand out to me though are if it is included like it is shown in the example, as a straight include:: then it feels no different from an include::_attributes.adoc[] type approach (the example is include::.asciidoctorconfig[])

The second bit, I like, is that there can be more than one existing, I guess if It worked more like a .gitignore, where it could overrides at that point?

So if I think about my workflow, where would the you have an antora project structure such as the following. There is the opportunity to have the file live within the pages directory (feels like it would have the same issues as I currently face with the _attributes.adoc approach), or probably more usefully in each of the specific module directories (ROOT, api, etc).

modules\
 ROOT\
   .asciidoctorconfig
   pages\
       .asciidoctorconfig
   partials
   images
 api\
   .asciidoctorconfig
   pages\
      .asciidoctorconfig
   partials
   images  

Having this added, might at least in vs-code, fix the antora issue for some people ?

[flatrick]

I've been playing with a setup that might share the root cause for this issue.

My setup looks like this:

• docs that will used in multiple documents are stored in sub-folders (connected to some separate git-repo for that particular (set of) document(s)).
• the various documents then include that particular (set of) "path/file.adoc"

This works just perfectly fine when using asciidoctor / asciidoctor-pdf to render the document, but the preview in VS Code fails to handle it.

ifeval::["{docname}" == "main"]
:imagesdir: legal/
endif::[]
ifeval::["{docname}" == "legal"]
:imagesdir: ./
endif::[]

When I add {docname} in the document to see what it prints out, all I get is {docname} instead of "main" or "legal" so I'm guessing this particular attribute is never processed in the preview.

[rdmueller]

@bovinemagnet - sorry, I didn't notice your comment until now.

The big difference between the .asciidoctorconfig and an include::_attributes.adoc[] is that the .asciidoctorconfig is only active in the editor and helps to fix some issues with the preview.

For instance, I use it to add a corporate style sheet for my previews in IntelliJ.

Another example is the fix for image previews with nested documents where you only define the :imagesdir: in the main document. Yes, it would help to fix the problem described by @flatrick

[thammegowda]

I used .asciidoctorconfig to insert some CSS style for HTML preview,

ifdef::backend-html5[]
++++
<style>
body {
font-family: "Linux Libertine O", "Helvetica"
}

h1, h2, h3, h4, h5 {
font-family: "Linux Libertine O", "Helvetica"
}
</style>
++++
endif::backend-html5[]

this <style> tag seems to be inserted before the Level 0 header/title, and it inturn causes the issue discussed here: https://github.com/asciidoctor/asciidoctor.js/issues/358#issuecomment-317235779

[rdmueller]

@thammegowda interesting that this warning does not pop up without the .asciidoctorconfig. But the warning seems to be correct and it also pops up if you add some more lines before your first title.

you can avoid it by adding a

:doctype: book

before your title or even in your .asciidoctorconfig.

hope this helps

[apupier]

Current state:

• Support of .asciidoctorconfig file at root of the workspace merged in master branch
• PR provided for support of .asciidoctorconfig.adoc file at root of the workspace
• Draft PR in progress for support recursively the .asciidoctorconfig file
• TODO:
  • At the beginning of each of the files, append :asciidoctorconfigdir: , this comes in handy to setup for example an imagesdir
  • Potentially provide a cache mechanism to avoid reading config file every time

[apupier]

Current state:

• Support of .asciidoctorconfig file at root of the workspace merged in master branch
• PR provided for support of .asciidoctorconfig.adoc file at root of the workspace. First round of review done. ready for a second one
• Draft PR for support recursively the .asciidoctorconfig file. In draft mode as it is based on https://github.com/asciidoctor/asciidoctor-vscode/pull/646 but a proposal of implementation with tests provided
• Draft PR At the beginning of each of the files, append :asciidoctorconfigdir: , this comes in handy to setup for example an imagesdir. In draft mode as it is based on https://github.com/asciidoctor/asciidoctor-vscode/pull/646 but a proposal of implementation is provided. No test for this precise part, not sure how to test it and not sure it is worthy.

TODO:

• Potentially provide a cache mechanism to avoid reading config file every time

[apupier]

Current state:

• Support of .asciidoctorconfig and .asciidoctor.adoc file at root of the workspace merged in master branch
• At the beginning of each of the files, append :asciidoctorconfigdir: , this comes in handy to setup for example an imagesdir.
• PR for support recursively the .asciidoctorconfig file is ready to be reviewed.

TODO:

• Potentially provide a cache mechanism to avoid reading config file every time. Not detected performance issue with my small use case so far.

[apupier]

Unless I forgot something, we have reached the same level of support than in IntelliJ.

A point to watch is if there is a performance issue. In this case, we could provide a cache mechanism to avoid reading config file every time. Not detected performance issue with my small use case so far. I think that we can open another issue if we observe that.

@Mogztter How release of new version is planned? Do you have an idea when this feature will be available in a released version? Do we have official "snapshot" extensions that can be tried? I can try to find some people in my organization to do some testing on it.

[sturtison]

This is a very nice feature and have just used it. Thank you to the contributors.

.asciidoctorconfig really helps to set up a repeatable, multi-IDE functional preview for people who are foundation level AsciiDoc users and use it on a casual basis. It also helps lower the bar for project adoption.

[ggrossetie]

Thanks for your feedback @sturtison !

@apupier I didn't mention it but I've released a new pre-release version. Please give it a try!