Docs library

The built-in docs library is written in Quarkdown and provides the standard structure for a docs document, with sidebars, navigation, and a table of contents.

This library is the recommended way to set up a documentation project, and it is what this wiki uses. It wraps the raw .doctype {docs} setup into a simple, customizable include.

When creating a project via quarkdown create, the generated project is already set up to use the docs library.

The first step is to import the library:

.include {docs}

You do not need to call .doctype {docs} yourself. The library handles it.

Project structure

A project that uses the docs library is expected to have:

• _setup.qd, containing shared configuration such as themes, fonts, custom functions and variables. This file is included automatically by the library.
• _nav.qd containing the navigation links that populate the page list sidebar. This file is included automatically by the library.
• main.qd, the home page of the documentation, and entry point of the compilation.
• Each other .qd file is a subdocument, and should include the library at the top:

  .docname {My page}
  .include {docs}
  
  Content goes here.

The library takes care of the following:

1. Setting the document type to docs
2. Including _setup.qd from the project root
3. Placing the navigation from _nav.qd in the left sidebar via .pagemargin and .navigation
4. Placing a table of contents in the right sidebar
5. Adding a decorative heading from .docname

Setup file

The _setup.qd file is a good place for project-wide configuration shared across all subdocuments.

.doclang {English}
.theme {darko} layout:{minimal}

.pagemargin {topright}
    [GitHub](https://github.com/iamgio/quarkdown)

Navigation file

The _nav.qd file contains the links that appear in the page list sidebar. It consists of a list of links to subdocuments, optionally grouped by decorative headings:

###! Getting started
- [Quickstart](quickstart.qd)

###! Topics
- [Page 1](page-1.qd)
- [Page 2](page-2.qd)
  - [Section A](page-2.qd#section-a)

The current page is automatically highlighted in the sidebar.

Customization

By default, the page list appears in the left sidebar and the table of contents in the right sidebar.

You can swap or change these positions by overriding two variables in your _setup.qd file:

.theme {darko}

.pagelistposition {righttop}
.tocposition {lefttop}

Orphan pages

Note that, by design, Quarkdown does not compile orphan source files. In order to be compiled as a subdocument, a source file must be referenced by another file, be it in _nav.qd or in the content of another page.