TLDR;

I want to consolidate a large, scattered collection of random notes of various personal utility into a single collection of Markdown files with YAML frontmatter for metadata. I want to be able to publish or export any or all of them using Pandoc as conversion engine. I decided on Zettlr for an editor, although this doesn’t matter that much, any basic code editor will do. Zettlr renders the Markdown visually while typing and has nice built-in search functionality that is aware of YAML frontmatter, and leaves the Markdown files entirely alone.

Structure

I use the following structure…

F:\ipse_paideia
├───YYYYMM
│   └───secure
└───assets
    └───media
        └───YYYYMM

Markdown files in the project root are generally organizational or functional (i.e. index.html). Notes are given file names in the pattern of YYYYMMDDHHMMSS-legible_label.md and placed in the matching YYYYMM folder. Images or other media in placed in assets/media/YYYYMM. I will address the secure subfolders later, for now it is sufficient to know they just hold more Markdown files using the same file name logic. Put files from the month that you want to keep secure in this subfolder.

Linking between files is strictly file relative, not root relative. To link an image to a Markdown file from a YYYYMM folder looks like ![Image Label](../assets/media/YYYYMM/image.jpg).

My scripting, templating, Pandoc defaults files, etc are in a seperate folder that is home to my development projects. My static website folder mirrors the Markdown folder, with additional files (404.html, .htaccess, favicon.ico, etc.) and additional assets folders for website resources (assets/css, assets/js, etc.). I keep copies of the web domain files, css, and js in subfolders of my development folder.

config.yaml

In my development folder I use config.yaml to define the root file paths and the assets child directory for use in my scripts.

Zettlr configuration

There’s nothing complicated about installation. Target the Markdown source directory as your workspace. The only setting that is important is to turn off Zettlr’s internal Pandoc for exports.

Otherwise, start writing. Stick to standard Markdown and YAML frontmatter keys until comfortable.

I also keep templates for other Zettlr export options, defined internally in Zettlr for use with the export function, in my development folder. (Atomic HTML, Typst PDF, whatever)

Tools to install

Python required. I used global installs rather than have to boot a virtual environment every time I want to use my project.

• Pandoc CLI
• StatiCrypt *(Tricky! Notes on install here
• Pagefind (Python module)
• Pico.css (use a standard, classed version) I extend this with a custom css file to play nice with Pandoc, and remove all Pandoc css while retaining the id and class definitions for leverage.

LUA filter

I use a lua filter during static site export to convert “.md” in links to “.html”, so that links work when writing and on the static site.

build_site.py

Basic functionality from the command line. Must be in the development folder to run! Do not run from another folder, I haven’t added path resolution to enable this yet.

Basic function: python build_site.py --force --verbose. By default the script will rebuild and re-encrypt all secure files, and request an encryption password to use. By default, it will only process new files. This is broken at the moment.

I need to refactor the script. It really can only work as a full rebuild, which makes writing a file and viewing the output in a back-and-forth workflow a nonviable option as the number of notes grows. It really only functions with --force and --verbose for monitoring via CLI. The only viable option is to use a matching Zettlr export profile to view the file in HTML form as you work.

I currently have an atomic HTML export option that does this, but without any of the menu options. I’ll have to look into this…