haccfiles/websites/docs.hacc.space/Readme.md
stuebinm 41d82ae436 meta: new structure
we decided to:
 - get rid of unused packages
 - simpify the directory layout since we only have one host anyways
 - move our docs (such as they are) in-tree
2024-01-11 23:49:26 +01:00

44 lines
1.4 KiB
Markdown

# 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.