107 lines
2.8 KiB
Markdown
107 lines
2.8 KiB
Markdown
# 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 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
|
||
```
|
||
|
||
What each command does:
|
||
|
||
- `build`: incremental site build.
|
||
- `clean`: removes generated output and cache.
|
||
- `rebuild`: clears output/cache and builds from scratch.
|
||
- `watch`: shows an in-place terminal dashboard, watches project inputs, and rebuilds automatically on change.
|
||
|
||
## Watch Mode
|
||
|
||
`watch` tracks:
|
||
|
||
- `notes/**`
|
||
- `reference.bib`
|
||
- `math-macros.md`
|
||
- `images/**`
|
||
|
||
The watch UI:
|
||
|
||
- uses the terminal’s current size to keep the dashboard within the visible screen,
|
||
- keeps recent build output in a bounded activity pane,
|
||
- avoids scrolling raw Hakyll logs through the terminal,
|
||
- can start a local preview server unless `--no-server` is passed.
|
||
|
||
## 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.
|