Create your site¶

After you've installed Zensical, you can bootstrap your project documentation using the zensical executable. Go to the directory where you want your project to be located and enter:

zensical new .

This creates the following structure:

.
├─ .github/
├─ docs/
│  ├─ index.md
│  └─ markdown.md
└─ zensical.toml

To learn more about the specific files and directories that are generated for you, please consult the usage guide for the new command.

Configuration¶

Zensical comes with many configuration options that have sensible defaults, which allows to build a documentation site with almost no configuration. site_name is the only required setting:¹

[project]
site_name = "My site"

Unless you're building documentation for offline usage, it's strongly recommended to specify the site_url setting as well, since it's a prerequisite for the following features:

• Instant navigation
• Instant previews
• Custom error pages

Preview as you write¶

Zensical includes a web server, so you can preview your documentation site as you write. The server will automatically rebuild the site when you make changes to source files. Start it with:

zensical serve

Point your browser to localhost:8000 and you should see:

Build your site¶

When you're finished editing, you can build a static site from your Markdown files with:

zensical build

The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. The site can be hosted on GitHub Pages, a CDN of your choice or your private web space.

If you intend to distribute your documentation as a set of files to be read from a local filesystem rather than a web server (such as in a .zip file), please consult the offline usage guide.