documentation's documentation
This commit is contained in:
parent
451ca603c2
commit
32b78f441b
2 changed files with 57 additions and 9 deletions
44
Readme.md
Normal file
44
Readme.md
Normal 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.
|
22
config.toml
22
config.toml
|
@ -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
|
||||
base_url = "https://hacc.4future.dev/hacc/infra/docs-zola"
|
||||
|
||||
# Whether to automatically compile all Sass files in the sass directory
|
||||
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"
|
||||
|
||||
# might be useful — this isn't a blog, obviously, but updates for new entries
|
||||
# could still be nice, I guess
|
||||
generate_feed = true
|
||||
feed_filename = "atom.xml"
|
||||
|
||||
build_search_index = true
|
||||
|
||||
taxonomies = [
|
||||
{ name = "categories", feed = false},
|
||||
]
|
||||
|
||||
[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
|
||||
|
||||
[extra]
|
||||
# Put all your custom variables here
|
||||
[extra] # user-defined keys
|
||||
|
||||
# site title text
|
||||
main_title = "haccfiles documentation"
|
||||
|
||||
# navbar entries
|
||||
main_menu = [
|
||||
{url = "$BASE_URL", name = "Home"},
|
||||
{url = "$BASE_URL/categories", name = "Categories"}
|
||||
|
|
Reference in a new issue