Slatians Hideout on the Interweb

This is a personal blog, projects and wiki site hosted at slatecave.net.

It is built using the zola static site generator.

Structure

• content/ - contains most of the sites text.
  • about/ - contains information about the site and myself, also home for the footer
  • blog/ - My blog
  • creations/ - A showcase of some things I made
  • notebook/ - A public personal wiki where I note down information I find useful
• meta/ - contains text snippets used by the templating
  • 404.md - The message shown on a 404 page
  • footer.md - The message shown in the footer
• static/ - static files, mostly assets
  • assets - site theme
    • banner_plasma - plasma banner theme
    • banner_slatecave-creations - banners for some projects
    • site_slatecave - slatecave theme
  • blog/.htaccess - old redirects, not served anymore
  • resources/badges/cc-by-nc-sa.eu.svg - an optimized CC BY-NC-SA badge. currently unused.
• templates - templates for generating the slatecave, see templates section
  • shortcodes - shortcodes used in the page sources
• banners.toml - contains configuration for the banner on each site.
• build.sh - a script for local building, also invokes tidy and reports markup issues.
• config.toml - configuration file for zola
• report.awk - used in build.sh, summarizes the output of the tidy tool.
• robots.txt - used by the robots.txt template to generate the robots.txt file.

Slatecave theme

Files:

• icons_dark/ - dark mode icons
• icons_light/ - light mode icons
• dragon.svg - Slate the dragon (in the uper right corner)
• favicon.png - The sites favicon
• gallery.css - Unused, probably broken
• slatecave_v2.css - Old slatecave theme (still works!)
• slatecave_v3.css - New slatecave theme

TODO: a bit more about how the theme works … in summary: semantic html with a few utility classes.

Templates

The slatecaves templating has grown quite a bit over the last year … I'll try to keep it brief.

Zola allows templates to extend another template and overwrite predefined template blocks, because of this all html templates extend base.html (which is quite a beast) and customize small parts of it.

Template Files:

• Special Templates:
  • base.html - base template all page templates extend
  • elements.html - macros that are probably only used on slatecave.net
  • helpers.html - template macro libary
  • robots.txt - generates the robots.txt file
• Page Templates:
  • 404.html - template for the 404 page
  • page.html - default page template, just extents base.html
  • blog-page.html - Blog pages have special titles
  • index.html - Template of the landing page, contains some interesting feed generation
• Section Templates
  • blog-index.html - blog index, groups blog-posts by year
  • creations-index.html)s-index.html - a pretty boring section template
  • notebook-index.html - currently unused template as the notebook is also a Taxonomy
• Taxonomy
  • taxonomy_list.html - A generic taxonomy list that has a term overview and a section with the contained articles for each term.
  • taxonomy_single.html - Not very polished listing of articles inside a term.
  • notebook/list.html - Reders the /notebook page, tries to feel like a section template, but allows foregin content.

Template configuration

[extra] values for sections and pages frontmatter:

• banner string Set a custom banner for the page
• preview_image string set a custom preview image for link previews using e.g. opengraph.
• hide_description bool stops the description from showing up in place of a left out first paragraph.

[extra] values for sections frontmatter:

• short_title string with a short title that is diplayed on a buttons leading to the section
• show_feed_link bool set to true to show the feed link on the page, make sure to also set generate_feed in the general section. (There is also an or in case zola decides to expose the generate_feed option as section.generate_feed.)

[extra] values for pages:

• pinned bool if the page is pinned it will always show up on the frontpage.

[extra] values for creation pages frontmatter:

• creation_status string sort creation status description.
• sourcecode_uri string the uri of the repository the project lives in.
• fork_of string name of the project this one is a fork of.
• fork_of_uri string uri to the project this one is a fork of.

Note: The date attribute will be displayed as the project start date.

Inline Template hints

The base.html template does some rearranging to make the section based layout with boxes possible without nightmare markdown, around h2 headlines. To mark sections as what they are one can place some inline hints about a section.

• <!--DISCLAIMER-SECTION--> adds a disclaimer class which could be addressed by some css
• <!--H-CARD-SECTION--> add a h-card class for use with microformats
• <!--LANGUAGE:de--> sets lang="de" on the section to mark it as being in german.

Taxonomies

Currently the following taxonomies are configured:

• notebook - to place a page inside the Notebook section
  • Guides - guides and tutorials
  • Cheatsheets - Lookup tables, snippets, Cheatsheets
  • Bookmarks - A little Web directory
• topics - What the article is about
  • Art
  • Desktop Ricing - see also screen locking
  • Electronics and Microcontroller
  • Mobile Linux - Linux on the phone
  • Networking - general, also ssh and such
  • Shell - Everything that has to do with Cli, Tui and Shellscripting
  • Tools - Expected overlap wit Shell and Web
  • Web - Everything that has to do with web technology
• lang - Programming/Markup Language
  • Bash - see also Sh
  • C
  • Css
  • Html
  • JavaScript
  • Lua
  • Python
  • Rust
  • Sh - see also Bash, tag with both if relevant
  • Vala

Note: Html, Css and JavaScript only when it is directly about those things, otherwise place it in the topic Web.

Shortcodes

Whenever a shortcut sourrounds something the follwoing pattern is meant:

{% shortcode() %}
*Markdown* goes [here](#)
{% end %}

dl

Sourrounding helper for cerating definition lists, line based.

{% dl() %}
Defintion Title
: Definition Item
: Another Item
My _Website_
: [slatecave.net](https://slatecave.net)
{% end %}

linklist

Sourrounds an ordinry markdown list, adds the link-list class to any <ul> tag inside that has no attributes.

{% linklist() %}
* [Foo Site](https://example.org/foo)
* [Bar Article](https://example.org/bar)
* [Baz Code Repository](https://codeberg.org/slatian/site-source.slatecave-net)
{% end %}

linkbutton

Creates a link button, also known as button-paragraph to the stylesheet, which is a paragraph with exactly one link inside.

It accepts some parameters:

• href mandatory, the destination url, if it starts with an @ zolas get_url function will be used to generate the url.
• txt optional markdown text for the button, alternatively it may sourround the text it contains, if none of the two the button just displays its href

{% linkbutton(href="https://slatecave.net")%} Check out slatecave.net, it has linkbuttons! {% end %}

figure

Sourround a markdown block with it to make it a HTML <figure> element.

It accepts some parameters:

• caption an optional html string that will be inserted before the contant as <figcaption>
• caption_after same as caption but insetrd after the figure content

{% figure(caption="Lua snippet that prints foo")%}
```lua
print(foo)
```

NOTE: this also inserted <pre> and <code> tags but they were removed in the favor of markdown proce4ssing and automatic syntax highlighting. Maybe it will be removed in the future to allow figures to be rendered in any markdown viewer.

webring_widget

This shortcode makes a webring widget with some fancy buttons and a frame around it.

It accepts some parameters:

• name mandatory, the webrings name
• headline_tag optional, defaults to p, the html tag type that shoudl be used for the headline (i.e. h2 or h3)
• previous_uri mandatory
• next_uri mandatory
• random_uri optional (if the webring supports jumping to a random site)
• search_uri optional (if the webring has a search engine)
• about_uri optional, the link to the webrings homepage
• about_link_text optional, custom text for the webrings homepage button