docs: update README and AGENT.md for the scripts layout

Assisted-by: Delta:zai-glm-5.3
This commit is contained in:
Klagarge committed 2026-10-10 21:02:59 +02:00
1 parent 36b2fc4188
commit 7207cfdbd0
2 files changed
+73 -14

No files matched your search

+55 -11
View File
@@ -1,20 +1,64 @@
# Yggdrasil
A knowledge base migrated to [Calepin](https://vincentarelbundock.github.io/calepin/), a Typst-based static site generator.
Personal knowledge base built as a static website with
[Calepin](https://vincentarelbundock.github.io/calepin/), a Typst-based static
site generator.
## Quick Start
## Layout
1. **Dependencies**: You need the `just` command runner.
2. **Bootstrap Toolchain**: Run `just tools`. This downloads pinned versions of `calepin` and `typst` into the `tools/` directory. No global installation is required.
3. **Build**: Run `just build` to generate the static site in the `public/` directory.
4. **Preview**: Run `just preview` or `just watch` to view the site locally.
- `site/` — website sources: `calepin.toml` + `.typ` pages
- `public/` — generated site (gitignored)
- `tools/` — pinned `calepin` and `typst` binaries (gitignored, downloaded on demand)
- `scripts/` — helper scripts used by the Justfile and CI
- `legacy_docs/` — the old Docsify documentation, kept unmodified for reference
## Adding Content
## Quick start
* Source files are located in `site/`.
* To add a page, create a `.typ` file and link it in the `site/calepin.toml` configuration under `[sidebar]` or `[pages]`.
* Categories are structured as subdirectories (e.g., `site/thermo/`) with their own `index.typ`.
`just` is the only prerequisite — the toolchain is downloaded and
checksum-verified into `tools/` on first use (no global installs, no cargo):
just # list recipes
just tools # download the pinned toolchain into tools/
just build # compile site/ into public/
just preview # build, then serve the site locally
just watch # rebuild on change and serve
just clean # remove public/ and build caches
## Adding a page
Create `site/<category>/<page>.typ`:
```typst
#set document(title: [Page title])
#metadata((title: "Page title", translation_key: "category-page")) <website-metadata>
#title()
= Page title
Content…
```
and reference it in `site/calepin.toml`:
```toml
[[sidebar.section.item]]
target = "<category>/<page>.typ"
```
Sidebar labels come from the page's `#metadata(...)` line, not from the config.
## Adding a category
1. Create `site/<category>/` with an `index.typ`, using
`#metadata((title: "Overview", ...))` for its sidebar label.
2. Add a `[[sidebar.section]]` named after the category in `calepin.toml`,
listing the index page and its sub-pages.
## Deployment
The site is built as a set of static files in the `public/` folder. A Gitea Actions workflow `.gitea/workflows/build.yml` runs on push to build and upload these files as an artifact. They can be deployed to any static host.
`just build` produces a fully static site in `public/`: HTML pages plus
`sitemap.xml`, `robots.txt`, and `llms.txt`. The Gitea Actions workflow in
`.gitea/workflows/build.yml` builds the site on every push with the same
pinned toolchain and uploads `public/` as an artifact for deployment to any
static host.