Grdr

GRDR

grdr is a tool to generate blogs and slideshows from markdown files

Up and Running

In order to get up and running, clone this repo and run cargo make rebuild. This will require cargo make. If you’re a cool kid and want to run this with podman, you can try cargo make kube. This may require aardvark-dns to be installed on your system, but I’m not quite sure why.

Front Matter

Metadata can be stored alongside the content of the file using a front matter system. For example:

title = README
date = 3333-12-31
author = Stephen M. Reaves
author_twitter = rpscln
author_twitch = rapscallionreaves
author_mastodon = rapscallionreaves
tags = ["grdr"]
description = Readme to understand GRDR
slides = false
rivets = []

Everything above should be at the top of the file and a --- is used as a separator. Everything about the --- is considered front matter. This KV system is used to generate content. For example, description is what shows up when listing all the posts, author_mastodon generates a link to a mastodon profile, tags lets posts be grouped together, and rivets allow us to extra parsing outside the bounds of regular markdown.

Rivets

The real meat and potatoes of this tool is the rivets system. Rivets are dynamic parsers to augment normal markdown.

Rivets need to be enabled in the front matter, and inside the content. You can think of the front matter being an on/off switch for certain rivets, and the rivet tags inside the content dictate which parts should be rendered through that particular rivet. Let’s look at an example.

Katex

The first thing people tend to want to do when using markdown is add latex. GRDR handles this with the katex rivet. To use the katex rivet, make sure the rivet is enabled in the front matter (i.e. rivets = ["katex", "some_other_rivet"]) and surround the latex content with rivet tags. In this case the opening tag will be $katex and the closing tag will be katex$.

So you can do:

$katex
f(\relax{x}) = \int_{-\infty}^\infty f(\xi\,)e^{2 \pi i \xi x} \,d\xi
katex$

And have pretty math functions rendered in the final HTML.

Graphviz

Another thing you can do is generate SVGs from Graphviz. Try enabling the graphviz rivet and adding this to your content:

$graphviz
strict digraph t {
  aa[color=green]
    subgraph v {
      aa[shape=square]
        subgraph vv{a2 -> b2}
      aaa[color=red]
        aaa -> bbb
    }
  aa -> be -> subgraph v { d -> aaa}
  aa -> aaa -> v
}
graphviz$

This will require the graphviz binary on your system.

Slides

GRDR can also present posts as slides. The first thing you need to is set slides = true in the front matter. Then everything between a header (#) and a break (___) will become a single slide. For example, this would be a set of three slides:

# Title

Use the left and right arrow keys to move throughout the slides.

___

## First page

Here is some text

___

## Another page

Here is some more

$graphviz
strict digraph t {
    bgcolor="transparent"
    label="Test Graph"
    fontcolor="white"
    beautify=true

    node[style="filled, rounded, bold" fillcolor="white"]
    edge[color="white" fontcolor="white"]

    aa[color=green]
        subgraph v {
            aa[shape=square]
                subgraph vv{a2 -> b2}
            aaa[color=red]
                aaa -> bbb [label="foo"]
        }
    aa -> be -> subgraph v { d -> aaa}
    aa -> aaa -> v
}
graphviz$

___

Showcase

Putting a git(lab|hub) url in between showcase tags will download the README file and put it in a drop down. For example:

$showcase
https://gitlab.com/reavessm/rea
showcase$

Hide

You can also put long content between hide tags and the content will be hidden behind a drop-down in the final html. You can also put a summary on the same line as the opening tag and that will be displayed when the drop-down is closed, in order to give some hints about what secrets you’re hiding.

$hide Super lots of text
foo
.
.
.
bar
hide$

Installing

Installing dependencies

Fedora

sudo dnf install rust-std-static-wasm32-unknown-unknown protobuf-compiler

Gentoo

echo 'dev-lang/rust clippy' >> /etc/portage/package.use/rust
echo 'dev-lang/rust rls' >> /etc/portage/package.use/rust
echo 'dev-lang/rust rustfmt' >> /etc/portage/package.use/rust
echo 'dev-lang/rust rust-src' >> /etc/portage/package.use/rust
echo 'dev-lang/rust system-bootstrap' >> /etc/portage/package.use/rust
echo 'dev-lang/rust wasm' >> /etc/portage/package.use/rust

sudo emerge --ask dev-lang/rust dev-libs/protobuf