docs/static/agent.md (2954B)
1 # Set up sqzass in this project
2
3 sqzass is a static site generator: markdown in, a directory of HTML out. One
4 binary, no runtime — no Node, no Python, no system libraries.
5
6 ## 1. Install
7
8 It is **not on crates.io**. `cargo install sqzass` will fail.
9
10 ```bash
11 curl -fsSL https://sqzass.sqzer.com/install.sh | sh
12 # with Rust: cargo install --git https://github.com/debuman/sqzass
13 # on Arch: yay -S sqzass
14 ```
15
16 ## 2. Scaffold and build
17
18 `init` writes three files and refuses to run where a `sqzass.toml` already
19 exists, so it cannot half-overwrite a site that is already there.
20
21 ```bash
22 sqzass init . # sqzass.toml, content/_index.md, templates/page.html
23 sqzass build -i . # writes public/
24 sqzass serve -i . # live reload on http://127.0.0.1:3000
25 ```
26
27 Two config keys are required: `title` and `base_url`. Everything else has a
28 default.
29
30 ## 3. Rules you cannot infer from the file tree
31
32 - Front matter is **TOML fenced with `+++`**, not YAML with `---`. `title` is
33 the only required field.
34 - Internal links are `@/section/page.md` — the *source path* under `content/`,
35 not the URL. The build rewrites it and resolves it to the reader's language.
36 - Images are different: use a root-absolute path, ``. `@/`
37 resolves against pages only, so `@/images/x.png` stops the build.
38 - Translations sit beside each other: `page.md` and `page.ko.md`.
39 - `page.content` is already HTML in templates, so it needs `| safe`. Templates
40 autoescape by default and reading an undefined value is an error.
41
42 ## 4. Errors are deliberate
43
44 An unresolved link, a template that does not exist, two pages claiming one URL,
45 a misspelled key in `sqzass.toml` or in front matter — each one stops the build
46 and names the file and line. There is no flag to downgrade any of them to a
47 warning. Fix the cause.
48
49 ## 5. Reading the output as a program
50
51 Runtime messages are in Korean. The identifiers are not: error codes and
52 `doctor` check names are ASCII and stable, so match on those rather than on
53 message text.
54
55 | Exit | Identifier | |
56 |---|---|---|
57 | `0` | | Success. |
58 | `1` | `SQZASS_E` | Unclassified failure. |
59 | `2` | | Bad command line (clap's code, not ours). |
60 | `3` | `SQZASS_E_CONFIG` | `sqzass.toml`. |
61 | `4` | `SQZASS_E_CONTENT` | Anything under `content/`. |
62 | `5` | `SQZASS_E_TEMPLATE` | `templates/`, `i18n/`, or a missing asset. |
63 | `6` | `SQZASS_E_IO` | Reading or writing failed. |
64 | `7` | | `doctor` found something at or above `--fail-on`. |
65
66 `--json` works on every command and prints one object to stdout — on failure
67 too, so a script reads one pipe.
68
69 ```console
70 $ sqzass build -i . --json
71 {"ok":true,"output":"public","pages":1}
72
73 $ sqzass doctor -i . --json
74 {"findings":[{"check":"base-url","file":"sqzass.toml","message":"…","severity":"warn"}],"gated":1,"ok":false}
75 ```
76
77 ## Full documentation
78
79 <https://sqzass.sqzer.com> — and <https://sqzass.sqzer.com/llms.txt> is a flat
80 list of every page with its description.