---
title: "Contributing"
description: "How to edit pages, the OKF frontmatter contract, verifying adapted content, and building the site locally."
type: Guide
tags:
  - About
  - Contributing
generated:
  by: "claude/opus-5"
  at: "2026-09-11T00:00:00Z"
sources:
  - id: carc-docs
    resource: "https://carc.unm.edu/docs/about/contributing/"
    title: "CARC Documentation: Contributing to these docs"
    author: "team:unm-carc"
---

# Contributing

This site is a git repository of Markdown files, built with
[Zensical](https://zensical.org){target=_blank} and structured as an
[Open Knowledge Format (OKF) v0.2](https://github.com/GoogleCloudPlatform/open-knowledge-format){target=_blank}
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** (:material-pencil:) 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:

```yaml
---
title: "Page title"
description: "One sentence used by search, indexes, and agents."
type: Guide        # Guide | Tutorial | Reference | Policy
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:

```yaml
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

```bash
git clone https://github.com/UNM-CARC/cyverse.git && cd cyverse
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 `/cyverse/`.
* 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/`.