HTML output, expand asciidoctor.css inline.

[wfouche]

Currently, when exporting an Asciidoc document to HTML from within Brackets, the asciidoctor.css file is referenced using an absolute local path (which would differ from machine to machine). For example, on my laptop the asciidoctor.css file lives here:

<link rel="stylesheet" href="file:///home/wfouche/.config/Brackets/extensions/user/nerk.asciidoc-preview/themes/asciidoctor.css">

This prevents me from emailing the HTML file to others to read as all the formatting is lost due to the style sheet being unavailable.

The fix for this is very simple (just inline expand the asciidoctor.css file in the HTML file). Simply replace

<link rel="stylesheet" href= .....

with

<style>
... contents of asciidoctor.css file
</style>

I've written a Python script to post-process the HTML file but it would simplify things if this step is not required.

Thanks,

Werner

[nerk]

In Asciidoctor (Ruby), linking versus embedding of style sheets is controlled by the 'linkcss' attribute. By default , the 'linkcss' attribute is not set and the style sheet is embedded,

However, the preview extension uses Asciidoctor.js for rendering. From my experience, Asciidoctor.js has some problems to directly read files from the local file system. Depending on the 'Safe Mode' defined in the settings dialog, accessing local files is prohibited anyway. That's the reason why the preview extension internally always sets 'linkcss' to true.

I could manually read the style sheet and insert it into the rendered output, pretty much like what your python script is doing. However, your document will still not be completely self-contained, because images will still be referenced externally.

If you really want to have a self-contained HTML document, I would recommend to use the regular Asciidoctor CLI and also define the 'data-uri' attribute. This will also embedd all images into the HTML.

I've already been thinking about an option for invoking the regular Asciidoctor CLI from the preview extension, which might be a more versatile way to create documents.

[nerk]

Asciidoctor.js open issues related to this:

https://github.com/asciidoctor/asciidoctor.js/issues/116 https://github.com/asciidoctor/asciidoctor/pull/1354

[wfouche]

In the meantime, I've also updated the Python script to Base64 encode images to make the HTML file truely self-contained.

Thanks for pointing out that AsciidoctorJ has this functionality built-in. I've tried running asciidoctorj from the command-line just now with options "-b html5 -a data-uri" and it generated a self-contained HTML file; Python script not required anymore.

It would still be nice though if the brackets-asciidoc-preview component could recognize the :data-uri: attribute in the Asciidoc header and generate a self-contained HTML file. See:

• http://asciidoctor.org/docs/render-documents/#managing-images

But since you are considering using the Asciidoctor CLI in the future, that to me sounds like the best approach going forward.

[nerk]

Glad it's working for you. AsciidoctorJ is, more or less, JRuby (Java implementation of Ruby interpreter) bundled with Ruby Asciidoctor. It's actually better suited to be used within your own Java application for processing Asciidoc, where you start it up once and then process documents repeatedly.

For processing of a document from the CLI, there is some significant overhead regarding initialization of the JVM, running JRuby which then executes Asciidoctor.

If you just want to run the Asciidoctor CLI and do not rely on Java-only Asciidoctor plugins, I would recommend installing Ruby. Then just run

gem install asciidoctor

to install Asciidoctor. After that, you can just invoke 'asciidoctor' from the commandline. Processing from the CLI should be much faster than AsciidoctorJ.

[nerk]

BTW, it is also possible to save the document from your browser as .mht file. See https://de.wikipedia.org/wiki/MIME_Encapsulation_of_Aggregate_HTML_Documents

This will include everything into a single MHTML file. Chrome and IE can render these files natively, for Firefox you'll need an additional plugin.

This might also be a convenient way to quickly share documents as a single standalone file.

[mojavelinux]

Cool tip @nerk!