77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# Yggdrasil
|
|
|
|
Personal knowledge base built as a static website with
|
|
[Calepin](https://vincentarelbundock.github.io/calepin/), a Typst-based static
|
|
site generator.
|
|
|
|
## Layout
|
|
|
|
- `site/` — website sources: `calepin.toml` + `.typ` pages
|
|
- `site/themes/yggdrasil/` — local theme extending the bundled `calepin` theme (scoped sidebars, academic-styled landing)
|
|
- `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
|
|
|
|
## Quick start
|
|
|
|
`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
|
|
just ci # run the CI workflow locally with act (needs act + docker)
|
|
|
|
## 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.
|
|
3. Add a `[[menus.main]]` entry with the category's `index.typ` as `target`
|
|
and the category name as `label` (e.g. `Home`, `IT`), so it appears in the
|
|
top navigation bar. The `label` is required here because the index page's
|
|
metadata title is `Overview`.
|
|
|
|
Pages inside a category show only that category's sidebar section — the
|
|
local theme (`site/themes/yggdrasil/partials/site-nav-sidebar.html`) filters
|
|
the sidebar to the section containing the current page. Pages outside every
|
|
category (landing page, `404`, standalone pages) fall back to the full
|
|
sidebar.
|
|
|
|
## Deployment
|
|
|
|
`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.
|