Best way to share asciidoc files?

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

Best way to share asciidoc files?

samir
Hi,
i just found out about asciidoc/asciidoctor 2 days ago and i love it so far.

There is one thing that bugs me or I'm not sure if i understood it.

If i put images in my. adoc file and render it as html i can see everything fine. But if i send that html file to a friend he doesn't see those images. If i try to convert it to pdf it doesn't look like the preview in html it basically looks like garbage as a pdf.

What is the best way to save the file so i can send it to everybody and they can see all the things

One thing more .If i turn off my internet connection and open an html file that i rendered with asciidoc/asciisdoctor all the TIP: and WARNING: icons disappear
Ted
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

Ted
samir wrote
What is the best way to save the file so i can send it to everybody and they can see all the things
Option 1 use Asciidoctor to generate a .pdf

If you want to share a document offline, I'd recommend using asciidoctor-pdf. Get it and install it here: https://github.com/asciidoctor/asciidoctor-pdf#install-the-published-gem

This way when you render your .adoc file all the images and admonition icons get embedded into the .pdf file.

Command to render pdf

> asciidoctor-pdf myDoc.adoc

This will produce a myDoc.pdf file that you could share with others.



Option 2 use Asciidoctor to generate HTML as you are doing.

When you use Asciidoctor to generate the HTML, you will need to share it and all the images too.

e.g.
myDoc.html
imageOne.png
imageTwo.jpg

The TIP and WARNING icons are using font-awesome which is linked via the Internet by this HTML:
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css">

For offline viewing: Does anyone know if there is an easy way to include the font-awesome.css into the HTML generated? And wouldn't you need the font-awesome fonts too?
- Ted @TedAtCIS
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

mojavelinux
Administrator

Ted wrote:
Option 2 use Asciidoctor to generate HTML as you are doing.

When you use Asciidoctor to generate the HTML, you will need to share it and all the images too.

You forgot about data-uri. If you enable the data-uri attribute, all images will be embedded directly into the HTML (using base64) so the file can be shared in isolation.

asciidoctor -a data-uri document.adoc


Does anyone know if there is an easy way to include the font-awesome.css into the HTML generated? And wouldn't you need the font-awesome fonts too?

Not currently. That's being discussed in the following issue:


Keep in mind, you don't have to wait for a change in core. You could implement your own template for the document node (e.g., document.html.slim) and implement the behavior there.

samir wrote:
If i turn off my internet connection and open an html file that i rendered with asciidoc/asciisdoctor all the TIP: and WARNING: icons disappear

If you unset the iconfont-remote attribute, Asciidoctor will attempt to load Font Awesome from the output directory.

asciidoctor -a icons=font -a stylesdir=css -a iconfont-remote! document.adoc

You need to organize the Font Awesome files as follows (which mirrors how they are packed in the Font Awesome distribution).

css/font-awesome.css
fonts/fontawesome-webfont.eot
fonts/fontawesome-webfont.svg
fonts/fontawesome-webfont.ttf
fonts/fontawesome-webfont.woff
fonts/fontawesome-webfont.woff2

This needs to be documented in the user manual. See https://github.com/asciidoctor/asciidoctor.org/issues/361.

-Dan

--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

samir
In reply to this post by Ted
asciidoctor-pdf  ftw .

Thank you Ted. I didn't know about this tool. This makes my life so much easier
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

samir
In reply to this post by mojavelinux
Hi Dan,

so data-uri is only for creating HTML files right ?

mojavelinux wrote
Keep in mind, you don't have to wait for a change in core. You could
implement your own template for the document node (e.g.,
document.html.slim) and implement the behavior there.

-Dan

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

Before i can start creating my own files i think i have to read the Asciidoc Writer Guide and Syntax Reference plus the
asciidoctor user manual again...

Thanks for the tip with data-uri
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

mojavelinux
Administrator

On Tue, Mar 29, 2016 at 2:15 PM, samir [via Asciidoctor :: Discussion] <[hidden email]> wrote:
so data-uri is only for creating HTML files right ?

Correct. In theory, any converter can make use of it if it makes sense in that output format. The built-in HTML converter uses it as well as some of the HTML slide converters.

-Dan


--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Best way to share asciidoc files?

sclassen
If you like the HTML better and want to share this then most browsers allow you the save a page for offline viewing.
This offline version (most of the time a *.html file plus a folder with pics, css, ...) of your page can then be shared.