AsciiDoc: how to specify HTML output fonts?

Question

Seeking simple instructions for a minimalistic way to specify the default output fonts (namely changing the font family to somthing like Calibri; but also want to control bold, italics, and other styling) in AsciiDoc input .txt file in order to change the HTML output.

Optionally: would like to make custom font change call-outs for specific parts of the document (say one or two lines in the content).

If css control is needed, I can handle that, but need every functional step spelled out in the procedure/setup.

Answer 1

I am new at AsciiDoc myself, but this might be enough to get you going. Unfortunately, there doesn't seem to be a really simple way to set custom styles with simple directives in your AsciiDoc input file. Ultimately, AsciiDoc just includes a stylesheet file into your output (after some fairly complex logic, depending on the backend).

The simplest alternative seems to be to create your own theme. The AsciiDoc User Guide has instructions on how to do this (sorta), but essentially:

1. Find the themes directory under wherever AsciiDoc is installed
2. Copy an existing theme ("flask" seems to be the default). Pre-version 8.6.6, it's just a set of CSS files. With 8.6.6 and above, it's a set of directories.
3. Edit the theme to your liking.
4. Specify the stylesheet using the theme document attribute or --theme <name> command line option (8.6.6. and later), or --attribute theme=<name> (pre-8.6.6).

The downside to this approach is that your theme has to exist with the other themes. There does not seem to be a way to change it, or I just don't know it. Symbolic links could work, if that's an option for your situation.

Another possibility is a little more extreme, but allows you to keep your style along with your data, if you'd prefer that. A little disclaimer: I figured this out by poking around the AsciiDoc source code, and it's not documented, so it might change in a later release. I doubt it, but it's worth noting. I've also only done a quick test with it, but it seems to work.

1. Create a configuration file if you don't have one already.
2. In it, create a [header] section (which is not a documented configuration file section, but I've noticed it in .conf files for the backends).
3. I don't know which backend you're using, but whichever it is, find its .conf file, look for the [header] section, copy the whole section, and paste it into your configuration file. There might be multiples, so look for whatever "looks right".

4. Edit the [header] section of your configuration file. Your goal is to pull out any sort of decision-making code. For example, for the html backend, which is just an alias for xhtml11, I'd remove the ifdef macros, and replace them with an include1 macro to include my CSS file. So what I'd end up with is something like this:

   [header]
   <DOCTYPE html ... yadda yadda
   <!-- snip: a bunch of meta elements and such -->
   <title>{title}</title>
   <style type="text/css">
   include1::style.css[]
   </style>
   

5. Tell AsciiDoc to use your configuration file, using the command line option or document attribute.

Tried this latter approach to "delete" the XHTML header from a sample I tried, but I didn't go beyond that. If the first approach is not to your liking, hopefully the second one works out.

As for a custom font change call-out, I'd probably use a passthrough block:

++++++++++++++
<span id="foo">content goes here</span>
++++++++++++++

But note that it's backend-specific, and that example is HTML, if I have it right (I'm a little rusty). I'm not familiar enough with AsciiDoc to suggest anything better.

Answer 2

I just started myself to look at Asciidoc and was irritated not to find a documented way of

1. linking to custom CSS style sheets
2. excluding the CSS section in the header of the output file.

Without taking all the steps which are described in Write your own AsciiDoc theme for HTML5 backend with SASS, I found at least the following for the command line:

asciidoc -b html5 -a linkcss -a stylesdir=$PWD myfile.txt

In this case, the name of the style sheet must be the default, i.e. asciidoc.css This fulfills the requirements mentioned above.

Answer 3

Expanding on the passthrough block (also mentioned above) trick I just learned about from https://stackoverflow.com/a/29456923/200509 , putting this somewhere in your .adoc file should enable to override any theme style (see /etc/asciidoc/themes/flask/flask.css for defaults), including fonts:

++++
<style>
body { font-family: Calibri,sans-serif; }
</style>
++++