gronk/readme.md

🦫 gronk

Formerly notes2web.

View your notes as a static HTML site. Powers notes.alv.cx.

Why?

• View notes as a website, on any device
• Easily share notes
• Powered by Pandoc, and therefore supports Pandoc's markdown (I mainly care about equations)
• flatnotes is cool but I really would rather type my notes in Vim
• Lightweight HTML generated
• Minimal JavaScript

Install

Docker

Run the following, modifing the -v arguments as needed to mount the correct folders and setting the value of ARCH to either amd64 or arm64 as appropriate.

docker build . -t gronk --build-arg ARCH=amd64 
docker run -v ./n:/usr/src/app/notes -v ./web:/usr/src/app/web gronk

Compose

A docker compose file file has been provided.

Set the following environment variables (or create a .env file) and run docker compose up:

• ARCH
• SOURCE
• OUTPUT

Locally

0. Install Pandoc and Pip, python3-dev, and a C compiler
1. sudo make install

Other Things to Know

• gronk indexes ATX-style headings for searching
• gronk looks for the plaintext file LICENSE in the root directory of your notes

Custom Directory Index and Metadata

To add custom content to a directory index, put it in a file called readme.md under the directory.

You can set the following frontmatter variables to customise the directory index of a directory:

variable	default value	description
blog	false	enable blog mode for this directory
tags	[]	list of tags, used by search and inherited by any notes and subdirectories
uuid	none	unique id to reference directory, used for permalinking
content_after_search	same as blog	show custom content in readme.md after search bar and directory index
automatic_index	true	show the automatically generated directory index. required for search bar to function.
search_bar	true	show search bar to search directory items. requires automatic_index (enabled by default)

Notes Metadata

gronk reads the following YAML frontmatter variables for metadata:

variable	description
author	The person(s) who wrote the article
pub_date	(for blog mode) set the publish date of an article/post/note (MUST be RFC822 format)
tags	A YAML list of tags which the article relates to - this is used for browsing and also
title	The title of the article
uuid	A unique identifier used for permalinks.
lecture_slides	a list of paths pointing to lecture slides used while taking notes
lecture_notes	a list of paths pointing to other notes used while taking notes

Blog Mode

A directory can be turned into a blog by enabling blog mode. This can be done by setting the blog variable to true in the readme.md custom directory metadata.

Notes under this directory will be published to a blog, whose feed is accesible at https://notes.alv.cx/notes/<directory..>/feed.xml.

When blog mode is enabled, it is required that the base_url property is set in the top level readme.md file. Note that there should be no trailing slash. If a readme.md file does not exist, then an empty one can be created:

---
base_url: https://notes.alv.cx
---

Permalinks

Permalinks are currently rather basic and requires JavaScript to be enabled on the local computer. In order to identify documents between file changes, a unique identifier is used to identify a file.

This unique identifier can be generated using the uuidgen command in the uuid-runtime package or str(uuid.uuid()) in the uuid python package.

The included n2w_add_uuid.py will add a UUID to a markdown file which does not have a UUID in it already. Combine it with find to UUIDify all your markdown files (but make a backup first).

Custom Styling

To completely replace the existing styling, set the environment variable GRONK_CSS_DIR to another directory with a file called styles.css.

To add additional styling, the default styling will attempt to import styles.css from the root of the notes directory.

To add additional content to the homepage, create a file called readme.md at the top level of your notes directory. To set the HTML title tag, set title in the frontmatter of readme.md:

---
title: "alv's notes"
---

# alv's notes

these notes are probably wrong

CLI Usage

$ gronk.py notes_directory

Output of gronk.py --help:

usage: gronk.py [-h] [-o OUTPUT_DIR] [-F] notes

positional arguments:
  notes

options:
  -h, --help            show this help message and exit
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
  -F, --force           Generate new output html even if source file was modified before output
                        html

The command will generate a website in the output-dir directory (./web by default). It will then generate a list of all note files and put it in index.html.

Then you just have to point a webserver at output-dir.

Uninstall

# make uninstall

Acknowledgements

Default synatx highlighting is based off Pygments' default theme and made using Pandoc v2.7.2. I found the theme here.