How can I add a generic page header with site navigation to an asciidoc document?

Question

I'm trying to build a basic documentation site using asciidoctor. One thing I am struggling with is how I can inject a standard site header (a banner with a logo and top-level navigation) into each documentation page.

I render my asciidoc directly to html from the command line. I have tried to find a way to somehow inject an extra div element and position it fixed at the top, but I can't figure out what mechanism to use for this. My early attempts involved using docinfo.html but that gets injected into the html in the <head> element, instead of the <body>.

I am aware that full-on publication systems like Jekyll allow me to configure "front matter" that can probably take care of this, but I was hoping there was a mechanism or trick using vanilla asciidoctor that can achieve this.

score 1 · Accepted Answer · edited Oct 18 '16 at 22:59

Ted Bergeron on the Mailing List mentioned a simple project:

Demo website created just using Asciidoctor.

Check the corresponding repo to see the files and how to create the site (just using one command).

In summary: simply create a header asciidoc file that includes your site nav (in the demo site this is done using table markup), without including a level-0 (document) title. Include this header file right at the top in every page of your site. Then render by just running asciidoctor *.txt on your project.

score 1 · Answer 2 · answered Jun 14 '19 at 09:07

--embedded option + simple post processing

With this option, asciidoctor generates only the interior part of the <body> element.

For example:

main.adoc

= Super title

== Second level

asdf

== Also second level

qwer

then:

asciidoctor --embedded main.adoc

produces:

main.html

<div class="sect1">
<h2 id="_second_level">Second level</h2>
<div class="sectionbody">
<div class="paragraph">
<p>asdf</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_also_second_level">Also second level</h2>
<div class="sectionbody">
<div class="paragraph">
<p>qwer</p>
</div>
</div>
</div>

You can then just cat a header and closing footer, and you are done.

Tested with Asciidoctor 2.0.10.

How can I add a generic page header with site navigation to an asciidoc document?

2 Answers2

Linked