The AsciiDoc Discussion


Have you seen this thread on Slate about the journey to AsciiDoc and why they aren’t doing it within the project?

The only thing Slate a baulking at is having to maintain an Asciidoctor Backend.


Heh, “only thing” for a project that doesn’t maintain any backend looks as though it was finally a dealbreaker. Thanks immensely for the pointer, @jaredmorgs!

Reading through the issue was very helpful. I’m thinking of pursuing a somewhat different option, although I’m now less certain of its viability. Part of what I’m advocating t to my new team is the more expansive markup of Asciidoc, and I suspect that documenting and using different backends for different parts of our project might be a dealbreaker – which if I’m understanding correctly would be involved if we created a whole new template. So I’m wondering whether fiddling on the front end, with the stylesheets, can give us what we need. I can imagine some issues, but I thought I’d see where I could get with this approach.

Or else I’ll have to learn Ruby … I suppose there are worse fates :wink:


I’ve taken a look at the file and you can do away with the “legacy” way (pure AsciiDoc) of marking up Headings if you are using Asciidoctor.

I’d be happy to modernise the file for you and bring it up to Asciidoctor 1.5.3 standards.

If you want to send me the post-processed version of the doc, I can match the heading nesting to the levels in the source doc easier.



Thanks very much for your offer!

We start with a README.txt file in asciidoc format.

At the moment, I convert it by hand, in two steps

a) I use asciidoctor -b docbook README.txt
b) I then apply sed commands in a script so I can set up the resulting DocBook file as a chapter. (I also need the option to set it up as a section)

We then use our maven tools to process this and our other DocBook files. So my asciidoc README.txt file ends up looking like this chapter.

Let me know if there’s any more info that you need.


So by the looks of the file, the .adoc content starts as a L1 heading. I could suggest ways of altering those code blocks, but don’t want to break any scripting you use. Asciidoctor is capable of mapping to Docbook almost flawlessly, so even if I do change the format of the code blocks you should be fine.

I’ll make a PR on that repo and you can see if anything breaks.


Massive PR incoming, Mike. Ping me on Slack if you want to chat about it.

To everyone reading this thread:

If you are new to AsciiDoc, please use and abuse my skillset to your advantage. Then pay it forward. Each one teach one. :smiley:


Update: a couple of months later. I have now ditched Sphinx, mostly because I am not too keen on restructuredText (rest), but I continue to love using asciiDoc. Actually I am using asciiDoctor. Plus I am learning Jekyll and slowly understanding how to combine the two. Together they give me way more capability for generating static web sites – perfect for writing docs, notes, journals, etc. – than Sphinx. So now I’m back to writing in asciiDoc pretty much exclusively, and I’m interested if anybody reads this on connecting with others also using Jekyll. Perhaps that should be a separate topic if there is interest.


For generating websites from .adoc files, I’ve had some good success with Asciidoctor in Jekyll. I’ve had better success using Hugo ( :: requires Asciidoctor installed to render .adoc files)


Thanks much. I am liking Jekyll, but I will take a look at Hugo. One issue I have with Jekyll is that it does not respect :toc: left (nor right I assume). An asciiDoc toc is always displayed under the main header. But when compiled natively by asciiDoctor, :toc: right is in a fixed scrollable panel. I have managed a work-around by tweaking the generated html class defs, but of course that’s no good since my changes are erased on the next build. Any idea if Hugo performs better in this regard?


I experimented with Hugo a bit and I’m able to get it to hang left in a fixed panel. By using

:toc: left

in the layouts\partials\head.html, you have to add an asciidoctor stylesheet, to get it to work.

In there you’ll find the .toc2 class which is putting the Table of Contents in the panel.

I hope that gives you some insight. I’ll bet Jekyll works the same way.


What I’d recommend is add your own stylesheet to take advantage of the asciidoctor rendered HTML.

You could create a little stylesheet, call it asciidoctor-toc.css. In there copy the pieces of the Table of Contents styles out of the Asciidoctor.css and tweak them yourself. That way you could get your left or right side block to fit within the Jekyll theme you are using.


I am already using asciidoctor.css and linking to it in _includes/head.html. Compiling the same .adoc post in Jekyll and asciidoctor produces different results in the generated html. In the Jekyll file I find

<div id="toc" class="toc">
<div id="toctitle">Table of Contents</div>

But in the asciidoctor generated html I find:

<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>

If I manually change the Jekyll html from toc to toc2, the toc is displayed left in a panel. I also changed the declaration (just after </head>) in the Jekyll html to

  <body class="article toc2 toc-left">

Now everything seems to work correctly with the scrollable toc on the left of the text. How do I get Jekyll to do the same for all of my adoc files? Is this maybe a discrepancy between stand-alone asciidoctor and the jekyll-asciidoctor plugin?


Since adding the toc2 class works. I would add that into your Jekyll template.

Try looking in _layouts\default.html

Change the <body> tag to your
<body class=“article toc2 toc-left”>

Then every page will have that class.

I think you are right that the Jekyll-Asciidoctor plugin must have old code or something?


I changed <body> to <body class="toc2 toc-left"> in default.html. Now the body moves to leave room for the toc on the left, but there is just a blank panel; the toc remains under the page title. Despite the change the generated html still shows <div id="toc" class="toc"> (PS: I’m not that versed in html css scss etc., but I don’t see anywhere else that a body class is defined. I tried not using asciidoctor.css but that had no positive effect on the problem, and I am using the dev ja plugin.)


Tom, I think until Jekyll-Asciidoctor adds the toc2 class correctly the only other thing you could do is alter your Asciidoctor.css style sheet

You’d have to experiment a bit, but if you renamed the ‘toc2’ classes to be ‘toc’ in this section of the stylesheet, you ought to be able to get your Table of Contents to move into the left panel.

@media only screen and (min-width: 768px) { #toctitle { font-size: 1.375em; }
body.toc2 { padding-left: 15em; padding-right: 0; } ...
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; padding-right: 0; }
#toc.toc2 { width: 20em; } ...

And remove the classes you added to the body tag in your Jekyll template.

I’m just speculating at this point, good luck.

The thing I like about Hugo is if it finds .adoc files, it tries to render them with the Asciidoctor version you have installed. (no plugin). But there are not as many themes: as Jekyll.

I have yet to find a perfect way to publish documents as a website.

I have a couple of lightweight concepts.

easy, you only need Asciidoctor, but pretty limited in style (see demo)

intermediate: requires a lot of html and css to customize:

advanced: requires grunt to produce a bootstrap website


With your suggestion, I got the menus to work. However, they are not scrollable. Taking a brute-force approach (when in doubt use a hammer), I replaced all instances of “toc2” with “toc” in a copy of asciidoctor.css. This moved the menus to the left as you suggested it might, but the post text was then obscured. To fix that I also modified my post.html layout to:

<div class="post-content" itemprop="articleBody">
    <body class="toc">
        {{ content }}

Only the <body> elements are new. Now the menus appear in a panel at the left and they seem to work correctly. The text is reformatted to the right. But as I said the menu panel is unfortunately not scrollable.

I found it odd that asciidoctor.css has defs for toc-right, but none for toc-left. Does that make any sense? Also, the change above in --watch mode causes AsciiDoctor to issue numerous warnings about “section titles” being “out of sequence.” Restarting Jekyll from scratch makes these errors go away. So, there seem to be conflicts still between Jekyll and the asciiDoctor plugin.

Thank you for your help. I will look at your other suggestions and I have begun looking at Hugo. It may be that Jekyll won’t work for me after all. It all seems a bit hit-or-miss and I do like asciiDoctor.


Indirectly related (and excellent news):


i user ascii doctor to create a PDF which does successfully and the created PDF is not presentable so i need a default theme to be applied or a custom theme to be applied on the document at the time of creating i use java maven to achieve this.And there are no clue for java i see for the ruby version.Can someone here guide me through the process?