mirror of
http://101.35.51.105:3000/congyu/Hakysidian.git
synced 2026-04-27 21:40:50 +08:00
131 lines
3.7 KiB
Markdown
131 lines
3.7 KiB
Markdown
|
||
# 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.
|