Hakysidian/readme.md

# Drawbacks

- currently all shared files (css, templates, csl files...) are stored in `~/.cabal/store/`. there will be a copy for every compile
- web preview needs a port. if you don't set port manually, you cannot preview two projects at the same time.



--------


# 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:

```text
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:

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

## Install

From this repository:

```bash
cabal build exe:hakysidian
cabal install exe:hakysidian
```

## Commands

The default CLI mirrors the common Hakyll workflow:

```bash
hakysidian build
hakysidian clean
hakysidian rebuild
hakysidian watch
```

`watch` also supports:

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

The dashboard is now an explicit TUI mode:

```bash
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.