middleman/middleman-asciidoc

Include paths incorrect

fredkelly opened this issue · 6 comments

Hola,

I'm using the following gem versions:

gem 'middleman', github: 'middleman', branch: 'v3-stable'
# ...
gem 'asciidoctor', '~> 1.5.0'

I have created the following .adoc files (e.g.);

/source/docs/my-file.adoc
/source/docs/includes/common/other-file.adoc
/source/docs/includes/my-doc/other-file2.adoc
/source/docs/images/image.png

I am running into difficulty when building with this structure, it seems the includes/images are not sourced from the correct directory and so I get errors like:

asciidoctor: WARNING: <stdin>: line 9: include file not found: /Users/fred/Projects/foobar/source/includes/common/other-file.adoc

and in the resulting my-file.html:

Unresolved directive in <stdin> - include::includes/common/other-file.adoc[]

I've tried to pass values for docdir etc. to the asciidoc command but to no avail. Is there a standard way of achieving this result, preferable only building the files in /source/docs/*.adoc (that is, not building the other include files and adding them to the sitemap).

Much appreciated.

The problem is that the AsciiDoc renderer in Middleman sets the base_dir to the source folder, so includes have to be relative to that location.

If you want to change the behavior, you can use a custom extension.

class AsciidoctorTweaks < Middleman::Extension
  def initialize app, options_hash = {}, &block
    super
    app.before do
      app.config[:asciidoc][:base_dir] = 'source/docs'
      true
    end
  end
end

::Middleman::Extensions.register :asciidoctor_tweaks, AsciidoctorTweaks

activate :asciidoctor_tweak

The before hook runs just before the page is rendered. I can't figure out how to get access to the path being rendered. If you can figure that out, then you can set the base_dir to the relative path of the file being rendered, then the includes would work properly.

We need to have a way to set the base_dir to the document directory in the configuration. You can see I posed this question in the source code here:

https://github.com/middleman/middleman/blob/v3-stable/middleman-core/lib/middleman-core/renderers/asciidoc.rb#L19

The current behavior is likely wrong, but we can't just change it outright as we may break sites...so we need to make it configurable.

Note that whatever we change in Middleman 3 we'll need to also change in this extension so we're ready when Middleman 4 comes.

Thank you for getting back to me; this seems to have partly solved my issue... I'm also finding that the built in extension is trying to build the individual included pages as well as their parent, is there a way to make middleman only compile files in the source/docs directory and not traverse each source/docs/includes/* file?

Thanks again!

The solution we've used to prevent partial files from being converted is to
prefix the file name (or directory name. in which they reside) with an
underscore. I'm not sure if that's implemented in the middleman
integration. If not, could you file an issue to add it?

Eventually solved this by passing docdir="" to asciidoc and then referencing it from my includes, e.g. nclude::{docdir}/_includes/.. (similar to asciidoctor/asciidoctor/issues/1175). Not ideal, but it's working for now.

This has to do with relative path resolution when there is no prefix (as you added). In general, I recommend using an attribute reference as you have done since it gives you more control in different environments.