Hakysidian/readme.md

hakysidian

hakysidian is a static site generator for note projects.

It is built on Hakyll, but packaged as a reusable CLI so you can run the same site generator across multiple note repositories without copying shared assets around. The executable bundles its shared css/, fonts/, templates/, favicon.ico, and bib_style.csl files with Cabal, then reads project-specific content from the current working directory.

What It Expects

Run hakysidian inside a project directory with this layout:

your-project/
├── notes/
│   ├── first-note.md
│   └── another-note.md
├── reference.bib
├── math-macros.md
└── images/              # optional

Required inputs:

• notes/: markdown notes to compile.
• reference.bib: bibliography used by Pandoc citeproc.
• math-macros.md: math macro definitions prepended before note parsing.

Optional inputs:

• images/: copied into the generated site as-is.

Shared assets are not required in each project. They come from the installed hakysidian package.

Output

By default, hakysidian writes:

• _site/: generated site output.
• _cache/: Hakyll cache and temporary files.

Note pages use clean URLs. For example:

notes/graph.md -> _site/notes/graph/index.html

Install

From this repository:

cabal build exe:hakysidian
cabal install exe:hakysidian

Commands

The default CLI mirrors the common Hakyll workflow:

hakysidian build
hakysidian clean
hakysidian rebuild
hakysidian watch

watch also supports:

hakysidian watch --host 127.0.0.1 --port 8000
hakysidian watch --no-server

The dashboard is now an explicit TUI mode:

hakysidian -tui
hakysidian -tui --host 127.0.0.1 --port 8000
hakysidian -tui --no-server

What each command does:

• build: incremental site build.
• clean: removes generated output and cache.
• rebuild: clears output/cache and builds from scratch.
• watch: runs Hakyll's normal watch workflow, prints build logs directly to the terminal, and rebuilds automatically on change.
• -tui: starts the interactive dashboard with explicit controls for watching and cleaning.

Watch And TUI

Both watch and -tui work against the same project inputs:

• notes/**
• reference.bib
• math-macros.md
• images/**

Normal watch behaves like a standard Hakyll watch command: it stays in the terminal, rebuilds when inputs change, and can start a preview server unless --no-server is passed.

-tui uses an alternate-screen dashboard that:

• uses the terminal’s current size to keep the dashboard within the visible screen,
• keeps recent build output in a bounded activity pane,
• can start a local preview server unless --no-server is passed,
• supports w to start watching, s to stop watching, c to clean, and q to quit.

The TUI requires an interactive terminal.

Notes Format

This generator is opinionated toward the current note pipeline in this repository:

• Markdown is parsed with Pandoc and custom theorem/callout handling.
  • math is rendered with MathML. looks good in firefox
  • sidenotes are supported
  • spacing between CJK chars and ascii is automatically handled by a filter.
• Citations are processed through reference.bib and the bundled bib_style.csl.
• math-macros.md is injected before parsing so note content and theorem titles can use the same macros.
• Notes are rendered with the bundled templates and stylesheet set.