From 32b78f441bf6dba18182b8e9a992ab1b04469b14 Mon Sep 17 00:00:00 2001 From: stuebinm Date: Wed, 5 Jan 2022 23:48:25 +0100 Subject: [PATCH] documentation's documentation --- Readme.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ config.toml | 22 +++++++++++++--------- 2 files changed, 57 insertions(+), 9 deletions(-) create mode 100644 Readme.md diff --git a/Readme.md b/Readme.md new file mode 100644 index 0000000..536c2c7 --- /dev/null +++ b/Readme.md @@ -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. diff --git a/config.toml b/config.toml index 7a47bc5..4550879 100644 --- a/config.toml +++ b/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"}