User guide

These are the steps for creating a site with Doxyte:

Write some docs.
```
mkdir docs
vim docs/index.md
mkdir docs/usage
vim docs/usage/index.md docs/usage/config.md
```
Pages can be nested in subdirectories, e.g. docs/usage/config.md, docs/install/linux/source.md.

See Markdown support for the list of Markdown features supported by Doxyte.

Create a config file named docs/config.toml that looks like this:

rootdir = "."
pages = [
  { path = "index.md", title = "Home" },
  { path = "usage/index.md", title = "Usage" },
  { path = "usage/config.md", title = "Configuration" },
]

See Configuration for details and customisation options.

Build the site:
```
doxyte -c docs/config.toml -o site
```
Check that the site looks like you expect by running a development server:
```
python3 -m http.server -d site/
```
Publish the site, according to the instructions provided by your web host.

E.g. for SourceHut Pages:
```
tar cvzf site.tar.gz -C site/ .
hut pages publish -d project.example.com site.tar.gz
```

Output

The generated site will have the same structure as your source directory. For the example above, it will look like this:

site/
├── index.html
├── usage/
│   ├── index.html
│   └── config.html
├── main.css
└── main.js

The navigation bar at the top of each page lists only the top-level pages (/index.html and /usage/index.html in this example).

There is a link at the bottom of each page to the next page, based on the order of the pages in the config file.

Linking between pages

To make links between the pages on your site within the text, use relative paths in the source file. E.g. if index.md contains a line like this …

See [Usage](usage/index.md) for details.

… the HTML file in the output will have a functioning link:

<p>See <a href="usage/index.html">Usage<a> for details.</p>

Generating a table of contents

To produce an outline of all the pages and sections on your site, run doxyte with the -toc flag. (This is how the Table of contents page for this site is generated.)

doxyte -toc -c docs/config.toml -o docs/toc.md

Feel free to include the output file itself in the page list in the config: it is ignored when running doxyte -toc.