Asciidoctor :: Discussion

--out-file for HTML output doesn't copy locally linked files

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

wolandscat

--out-file for HTML output doesn't copy locally linked files

I tried the --out-file option on asciidoctor for the default HTML output, and it generates only the root html file and the css. To do this operation properly, it should copy all linked files in their original directory structure, to generate a self-standing static website.

Is there some other option that enables this behaviour?

mojavelinux

Re: --out-file for HTML output doesn't copy locally linked files

Administrator

Asciidoctor does not implement resource copying. The --out-file option only manages (and thus copies) assets generated by the processor itself (which include the HTML and CSS).

The reasoning is that Asciidoctor (core) follows the Unix philosophy: do one thing and do it well. Other functionality, such as resource management, is better handled by a dedicated tool...and we have many tool integrations from which to choose. Many people use the plugins for build tools (like Gradle and Maven) to handle this process. Others use static-site generators (like Jekyll, JBake, Awestruct or Middleman).

I strongly recommend using one of these options.

...I could also suggest another possible approach that maintains Asciidoctor as the top-level command. You can create an extension, such as a Postprocessor (or DocinfoProcessor), that copies the related assets to the destination directory. Then, you simply activate the extension when invoking Asciidoctor. That would be a good candidate for the extensions lab (https://github.com/asciidoctor/asciidoctor-extensions-lab).

Cheers,

-Dan

On Wed, Jun 17, 2015 at 4:28 PM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I tried the --out-file option on asciidoctor for the default HTML output, and it generates only the root html file and the css. To do this operation properly, it should copy all linked files in their original directory structure, to generate a self-standing static website.

Is there some other option that enables this behaviour?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/out-file-for-HTML-output-doesn-t-copy-locally-linked-files-tp3403.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

wolandscat

Re: --out-file for HTML output doesn't copy locally linked files

Agree on the principle of each-tool-for-its-thing. However it occurred to me that an asciidoc source file may be sitting above / next to some resource directories like 'diagrams', 'classes', 'images' and so on. Let's assume these directories have hundreds/thousands of resources, but that any given document only uses certain ones.

So the 'copy' function actually needs access to the information (which files, from where) obtained in asciidoc or asciidoctor processing - i.e. it's a filtered copy.

I would consider this a legitimate function of asciidoctor, since 'publishing' isn't some dumb copy, but a smart extract from the doc source area to a publish area.

thoughts?

mojavelinux

Re: --out-file for HTML output doesn't copy locally linked files

Administrator

You have a very good point. And this is exactly what an extension is able to do.

An extension, a Postprocessor in particular, has access to all the resources that Asciidoctor visited in the course of parsing the document (though some improvements still need to be made to the API, see below). The extension can then do something with these resources, such as copy them.

Since what needs to be done is going to be highly dependent on use case, anything that Asciidoctor core tries to do is going to come up short (as we have observed in AsciiDoc Python). Thus, the best thing we can do is make the information that the processor maintains about these resources as robust as possible.

We actually need to open an issue about improving the information stored about linked assets. For instance, we are only storing the target of an image {1}, but that drops the context, such as the value of the imagesdir at the time when an image is encountered.

-Dan

{1} https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/substitutors.rb#L678

On Thu, Jun 18, 2015 at 2:05 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Agree on the principle of each-tool-for-its-thing. However it occurred to me that an asciidoc source file may be sitting above / next to some resource directories like 'diagrams', 'classes', 'images' and so on. Let's assume these directories have hundreds/thousands of resources, but that any given document only uses certain ones.

So the 'copy' function actually needs access to the information (which files, from where) obtained in asciidoc or asciidoctor processing - i.e. it's a filtered copy.

I would consider this a legitimate function of asciidoctor, since 'publishing' isn't some dumb copy, but a smart extract from the doc source area to a publish area.

thoughts?

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/out-file-for-HTML-output-doesn-t-copy-locally-linked-files-tp3403p3406.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen | http://google.com/profiles/dan.j.allen

wolandscat

Re: --out-file for HTML output doesn't copy locally linked files

I see. Looks like extensions will be my next thing to learn!
Thanks.

mojavelinux

Re: --out-file for HTML output doesn't copy locally linked files

Administrator

On Thu, Jun 18, 2015 at 2:51 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:

I see. Looks like extensions will be my next thing to learn!

They open up a world of possibilities...and we want it to be that way. Extensions are where innovation happens!

Cheers,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen