___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

[ Home | What is AsciiDoxy? | Getting started | Reference documentation | Examples | Contributing | Changelog | GitHub ]

Multipage documents

The HTML output from AsciiDoctor is limited to a single HTML page. You can separate your document into multiple AsciiDoc files and use include:: to combine them, but this will result in a single large HTML file. Alternatively, you can create multiple AsciiDoc files and run AsciiDoctor separately on each file. This does create multiple HTML files, and you can even link between these files. However, it does not provide structured navigation between the files, and manual work is required to generate a single PDF version of the same documentation.

AsciiDoxy removes these limitations by introducing multipage mode. You can generate single HTML or PDF files in single page mode, and generate multiple HTML documents in multipage mode. All from the same AsciiDoc source files.

1. Structuring your multipage document

AsciiDoxy copies the input files to a temporary location where it can modify them. This is required to process the included python code. To be able to include, and refer to, other files, you need to tell AsciiDoxy where these files are. AsciiDoxy will then copy these files to the temporary location as well.

Let’s start by creating a directory with 2 AsciiDoc files:

  1. Create a directory called src. This will be the directory used by AsciiDoxy to find all files.

  2. In the src directory create a file called index.adoc. This will be the entry point for the generated documentation.

  3. In the src directory create another file called reference.adoc. This will be the second page of the documentation.

Run AsciiDoxy on these files:

asciidoxy --base-dir src src/index.adoc

The result will be a single, mostly empty file: build/output/index.html.

2. Including another file

Let’s first add some content to src/reference.adoc:

= Reference

This is the reference file.

Then add the following content to src/index.adoc:

= Documentation

This is the entry point of the documentation.

${include("reference.adoc")}

The last line is AsciiDoxy’s version of include::. Similar to the normal include:: this tells AsciiDoxy that you want to include the contents of another file here in the document. However, in a moment you will see that this version can do much more.

The path provided in the include command must be a path relative to the current document. Absolute paths are not allowed. This also means that parent directories can be referred to using ...

Run AsciiDoxy again:

asciidoxy --base-dir src src/index.adoc

The result will look something like this:

Documentation

This is the entry point of the documentation.

Reference

This is the reference file.

This is still the same result as using AsciiDoctor with include::! However, the result will be different when using AsciiDoxy in multipage mode:

asciidoxy --base-dir src --multipage src/index.adoc

There will now be 2 files: src/index.html and src/reference.html. The first one will look like this:

Documentation

This is the entry point of the documentation.

Reference

The link called Reference will take you to a file containing only the contents of reference.adoc. Both pages will also have a navigation bar at the bottom. With the navigation bar you can easily jump between pages.

3. Improving what the link looks like

By default, AsciiDoxy uses the first title detected in the included file for the link text. If it fails to detect a title the stem of the file name is used. An alternative text can be provided using the link_text argument:

${include("reference.adoc", link_text="Reference documentation")}

The result is:

Reference documentation

A link prefix can be used to insert text before the link, e.g. to create a list of links. This text will only be inserted in multipage mode. In singlepage mode the contents of the file are inserted.

${include("reference.adoc", link_text="Reference documentation", link_prefix=". ")}

  1. Reference documentation

For more options, see the documentation for include.

4. Cross-references between pages

In multipage mode, the usual AsciiDoc cross-references between different files no longer work as expected. AsciiDoctor relies on having all references in the same output file. When the target of the cross-reference is in a different output file, the cross-reference needs to be adapted.

AsciiDoxy can generate the correct cross-references for both singlepage and multipage mode. Instead of <<…​>> or xref:…​[], you need to use ${cross_document_ref(…​)}.

In the document structure from section 1 we can add the following to src/reference.adoc to refer to the main document:

${cross_document_ref("index.adoc")}

Documentation

AsciiDoxy takes the first title found in the document. If it cannot parse the file, it will use the stem of the file name: index in this case.

Similar to the include command, the provided path must be a path relative to the current document. Absolute paths are not allowed.

If the default link text is not what you want, you can override the text using the link_text argument:

${cross_document_ref("index.adoc", link_text="Back home")}

Back home

Optionally, you can provide an anchor to link to. For example in src/index.adoc:

${cross_document_ref("reference.adoc", anchor="_reference", link_text="Reference")}

Reference

For more options, see the documentation for cross_document_ref.

5. More to come…​

The AsciiDoxy documentation is still being written. Expect more documentation about:

  • Hiding multipage links

  • Showing a multipage table of contents

  • …​

AsciiDoxy