Skip to content

Contributing

This site is a git repository of Markdown files, built with Zensical and structured as an Open Knowledge Format (OKF) v0.2 knowledge bundle — every page is readable by people and consumable by AI agents, with provenance and trust signals in its frontmatter.

Small fixes

Every page has an edit button () in the upper right that opens the source file on GitHub. Fix the text, propose the change, and CI validates and deploys it once merged.

The frontmatter contract

Every content page starts with YAML frontmatter. type is required by OKF; the rest make the page trustworthy and discoverable:

---
title: "Page title"
description: "One sentence used by search, indexes, and agents."
type: Lesson        # Lesson, Guide, Reference, Policy, or Schedule
tags:
  - Containers
generated:
  by: "human:yournetid"       # who/what wrote the current content
  at: "2026-09-11T00:00:00Z"
sources:                      # where the content came from (optional)
  - id: upstream
    resource: "https://github.com/..."
    title: "Original source"
    author: "team:cyverse"
status: stable                # draft | stable | deprecated (default: stable)
---

Section index.md files are OKF directory listings and carry no frontmatter; log.md is the bundle's dated change log — add an entry when you make a meaningful change. Every page must also be listed in the nav of zensical.toml.

Verifying adapted pages

Pages adapted from CyVerse materials were migrated by an agent and are intentionally unverified. When you review one and confirm it is correct, record it:

verified: { by: "human:yournetid", at: "2026-09-15T00:00:00Z" }

If a page is obsolete, set status: deprecated, add a note pointing at the replacement, and log the change in log.md.

Building locally

git clone https://github.com/UNM-CARC/foss.git && cd foss
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt        # Python 3.11+
zensical serve                         # live preview at localhost:8000
python3 scripts/okf_validate.py docs   # OKF conformance check (runs in CI)
python3 scripts/check_links.py docs    # links, images, nav coverage (runs in CI)
python3 scripts/gen_llms_txt.py        # regenerate llms.txt indexes (CI checks drift)

Style notes

  • One # H1 per page, matching the frontmatter title.
  • Relative links between pages (../section/page.md); never site-root links (/section/page/), because the site is served under /foss/.
  • External links get {target=_blank} — scripts/externalize_links.py adds them for you.
  • Admonitions (!!! note, ??? question) for asides; content tabs (=== "macOS") for OS-specific instructions.
  • Keep images next to the section that uses them, under docs/assets/.