README.md (4353B)
1 # sqzass
2
3 A static site generator written in Rust.
4
5 Most generators lean on their host for pretty URLs, redirects and cache headers.
6 sqzass does that work itself, so the same output is correct on GitHub Pages,
7 Vercel, Cloudflare Pages, or a plain directory served over HTTP.
8
9 > **Status: early, and honest about it.** The pipeline works end to end —
10 > markdown, sections, templates, syntax highlighting, table of contents, the
11 > asset pipeline, search, a dev server with live reload, sitemap, robots.txt and
12 > Atom feeds.
13 > The documentation site at <https://sqzass.sqzer.com> is built with it, from
14 > `docs/` in this repository, and CI builds that site with the binary it just
15 > compiled. There is no theme system yet.
16
17 ## Install
18
19 ```bash
20 curl -fsSL https://sqzass.sqzer.com/install.sh | sh # static binary
21 cargo install --git https://github.com/sqzer-x/sqzass # from source
22 yay -S sqzass # Arch, from the AUR
23 ```
24
25 Every release also carries the tarballs directly, for Linux on x86_64 and ARM64
26 and for Apple-silicon macOS, each with a `.sha256` beside it. Details are in
27 [Installation](https://sqzass.sqzer.com/start/installation/).
28
29 ## Quick start
30
31 ```bash
32 sqzass init mysite
33 sqzass serve -i mysite
34 ```
35
36 `init` writes three files — `sqzass.toml`, `content/_index.md` and
37 `templates/page.html` — and `serve` puts them on <http://127.0.0.1:3000> with
38 live reload. `sqzass build -i mysite` writes the site to `mysite/public`.
39
40 Front matter is TOML, fenced with `+++`. `title` is the only required field.
41
42 ```markdown
43 +++
44 title = "Installation"
45 weight = 10
46 +++
47
48 Body goes here.
49 ```
50
51 ## Design
52
53 - **Markdown on the AST, not on the output.** Link rewriting, heading anchors and
54 the table of contents are tree operations via [comrak]. Running regexes over the
55 final HTML — the common shortcut — silently skips any element whose attributes
56 are single-quoted or unquoted.
57 - **Broken references stop the build.** An unresolved `@/` link, a missing
58 template, two pages claiming the same URL, an unknown asset name, a misspelled
59 configuration key — each is an error, not a warning you scroll past.
60 - **Templates resolved from a snapshot.** `templates/` is read into memory once per
61 build and [minijinja]'s loader serves `include`/`extends` from that snapshot, so a
62 rebuild triggered mid-save can never ingest a half-written partial.
63 - **Autoescaped by default.** `| safe` is opt-in, and undefined variable access is
64 an error rather than an empty string.
65 - **Highlighting emits classes, never inline styles.** Inline colours pin one
66 theme into every document forever: dark mode becomes impossible without
67 rebuilding, and a strict `style-src` is off the table.
68 - **Reproducible.** Two builds of the same input are byte-identical, and CI
69 checks it on every push.
70 - **Korean was not bolted on afterwards.** `page.md` and `page.ko.md` sit side by
71 side, `@/` links resolve to the reader's language, and untranslated pages are
72 absent from that language's navigation rather than duplicated or 404ing.
73 Search matches substrings rather than words, which is the only way `최적화`
74 inside `검색엔진최적화` is ever found.
75 - **One binary, no runtime.** No Node, no Python, no system libraries.
76
77 Runtime messages — `--help`, errors, `doctor` findings, the dev server log — are
78 in Korean, with no locale switch. Error identifiers (`SQZASS_E_CONTENT`) and
79 `doctor` check names are ASCII and stable, so scripts have something to match on.
80
81 ## Building
82
83 ```bash
84 cargo build --release
85 ```
86
87 Requires Rust 1.97 or newer. Nothing else.
88
89 <details>
90 <summary>Optional: faster linking with mold</summary>
91
92 `.cargo/config.toml` is gitignored, because a linker choice is a property of your
93 machine and not of this project — committing one forces it on everyone who clones
94 and on CI. If you have [mold] installed, create the file yourself:
95
96 ```toml
97 [target.x86_64-unknown-linux-gnu]
98 rustflags = ["-C", "link-arg=-fuse-ld=mold"]
99 ```
100
101 Note `-fuse-ld=mold` is the gcc spelling; `--ld-path=` is clang-only and gcc
102 rejects it.
103
104 [mold]: https://github.com/rui314/mold
105 </details>
106
107 ## Documentation
108
109 <https://sqzass.sqzer.com> — built with sqzass, from `docs/` in this repository.
110
111 ## License
112
113 MIT
114
115 [comrak]: https://github.com/kivikakk/comrak
116 [minijinja]: https://github.com/mitsuhiko/minijinja