maischberger.it is our family recipe book. Recipes are written in Markdown so that they can be maintained in Obsidian or any text editor, reviewed on GitHub, and published as a searchable static website.
| Path | Purpose |
|---|---|
docs/ |
Website source and home page |
docs/Basi/ |
Preparations and reference notes used by other recipes |
docs/Dolci/ |
Desserts and sweet baking |
docs/Pane e pizza/ |
Bread, buns, focaccia, and pizza |
docs/Primi/ |
Pasta, rice, soups, and other first courses |
docs/Salse/ |
Sauces and condiments |
docs/Secondi/ |
Main courses |
docs/images/ |
Shared recipe and site images |
Templates/Recipe.md |
Starting point for a new recipe |
overrides/ |
Theme templates, including comments and the custom 404 page |
zensical.toml |
Site metadata, Material theme, search, tags, and analytics |
.github/workflows/ |
Pull-request checks and deployment automation |
Recipe categories are represented by directories rather than a manually maintained navigation list. This keeps the site structure aligned with the Obsidian vault and lets the site generator derive navigation from the files.
- Copy
Templates/Recipe.mdinto the appropriate category underdocs/and rename it to match the recipe. - Update the YAML front matter. Keep
tagsas a YAML list and leavecomments: "true"enabled when comments should appear on the page. - Replace the placeholder image, introduction, ingredients, preparation, and tips.
- Put images in
docs/images/and link them relative to the recipe—for example,. - Preview the site and run the formatting check before opening a pull request.
The recipe template is the single source of truth for recipe structure and contains examples of supported Markdown. Update it directly when the shared format changes instead of duplicating those conventions here.
Use standard Markdown links with explicit relative paths. Obsidian can resolve short wiki links automatically, but the website generator, GitHub, VS Code, and other Markdown readers may not. For example:
[Pasta all'uovo](../Basi/Pasta%20all'uovo.md)
The project requires Python 3.11.15 and pins its site-generator dependency in
pyproject.toml. With uv installed:
uv sync
uv run zensical serve -f zensical.tomlOpen the local address printed by Zensical. To produce the same static output used for deployment, run:
uv run zensical build -f zensical.tomlFormatting is checked with Prettier in CI:
npx prettier --check '**/*.{yml,md}'- Pull requests and pushes to
mainrun the Prettier check in.github/workflows/check.yml. - Pushes to
mainalso run.github/workflows/build.yml. - The build workflow creates a release tag, builds the site with Zensical, and
publishes
site/to the GitHub Pages branch. docs/CNAMEassigns the published site tomaischberger.it.
The current layout is small and easy to browse: all recipes follow the same category-based structure, media is centralized, and the template establishes a recognizable page format. The main opportunities are consistency and automated validation rather than a structural rewrite.
Recommended order of work:
- Validate internal links and images in CI. This prevents Obsidian-only links or renamed assets from reaching the published site.
- Standardize recipe metadata. Define the supported front-matter fields and a controlled set of category and author tags, then normalize existing recipes.
- Complete recipe content. Replace remaining placeholder images and sample template text, and check ingredient units and preparation numbering.
- Improve discovery. Add short category landing pages only if automatic navigation and tags become insufficient as the collection grows.
- Document editorial conventions. Agree on language, capitalization, serving notation, units, image alt text, and optional source attribution.
These steps preserve the current Obsidian-friendly workflow while making the published result more predictable and easier to maintain.