documentation's documentation

This commit is contained in:
stuebinm 2022-01-05 23:48:25 +01:00
parent 451ca603c2
commit 32b78f441b
2 changed files with 57 additions and 9 deletions

44
Readme.md Normal file
View file

@ -0,0 +1,44 @@
# Markdown docs with zola.
[Zola](https://www.getzola.org/) is a static site generated written in Rust
(which you'll notice since sometimes it panics).
To run the site locally:
```
zola serve
```
## Directory Layout
All the important stuff goes into `content`. If you create subdirectories, make
sure you remembered to also create an `_index.md` file for it (if in doubt, just
copy the one at `content/_index.md`); otherwise pages in there won't work.
`templates` is *not* for site templates, but specifies how markdown files should
be turned into html. If an autogenerated link broke, you'll probably have to
change something in there. `sass` and `static` do exactly what they sound like.
It usually shouldn't be necessary to change `config.toml`, but if it is, [here
is the list of all available options](https://www.getzola.org/documentation/getting-started/configuration/).
## File Layout
Markdown files start with a frontmatter that should look something like so:
```markdown
+++
title = "blåhaj"
taxonomies.categories = [ "flausch" ]
+++
[actual markdown goes here]
```
The frontmatter is TOML; the `taxonomies.*` keys are special and can be used to
aggregate posts if enabled in `config.toml` (currently that's only the case for
`categories`, though). See also the [list of all available keys](https://www.getzola.org/documentation/content/page/).
Please don't repeat the page's title in markdown, otherwise it'll appear twice
in the html.

View file

@ -1,30 +1,34 @@
# Zola's configuration file,
#
# see https://www.getzola.org/documentation/getting-started/configuration/
# for available keys.
# The URL the site will be built for # The URL the site will be built for
base_url = "https://hacc.4future.dev/hacc/infra/docs-zola" base_url = "https://hacc.4future.dev/hacc/infra/docs-zola"
# Whether to automatically compile all Sass files in the sass directory
compile_sass = true compile_sass = true
# Whether to build a search index to be used later on by a JavaScript library
build_search_index = true
default_language = "en" default_language = "en"
# might be useful — this isn't a blog, obviously, but updates for new entries
# could still be nice, I guess
generate_feed = true generate_feed = true
feed_filename = "atom.xml" feed_filename = "atom.xml"
build_search_index = true
taxonomies = [ taxonomies = [
{ name = "categories", feed = false}, { name = "categories", feed = false},
] ]
[markdown] [markdown]
# Whether to do syntax highlighting
# Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
highlight_code = true highlight_code = true
[extra] [extra] # user-defined keys
# Put all your custom variables here
# site title text
main_title = "haccfiles documentation" main_title = "haccfiles documentation"
# navbar entries
main_menu = [ main_menu = [
{url = "$BASE_URL", name = "Home"}, {url = "$BASE_URL", name = "Home"},
{url = "$BASE_URL/categories", name = "Categories"} {url = "$BASE_URL/categories", name = "Categories"}