docs: update README and AGENT.md for the scripts layout
Assisted-by: Delta:zai-glm-5.3
This commit is contained in:
2 files changed
+73
-14
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user