Healthy Rivers and Landscapes documentation website

Disclaimer: this site is currently published in draft form, aligned with HRL's commitment to open source work, and should not be cited as authoritative HRL policy. It is released with an MIT license.

The Healthy Rivers and Landscapes program (HRL) is an eight-year interagency effort to restore aquatic habitat, provide environmental flows, and adaptively manage ecosystems in the Sacramento River watershed and the Bay-Delta estuary. HRL aims to support California's native fish populations and is proposed as part of the program of implementation for the State Water Resource Control Board's Bay-Delta Water Quality Control Plan.

HRL implementation and adaptive management is guided by a comprehensive Science Program that facilitates research into the impacts of integrated environmental flows provision and habitat restoration from upper Sacramento River tributary watersheds to the Bay-Delta estuary. The HRL Science Program is governed by a Science Committee composed of representatives from HRL signatory entities and other technical experts.

For more information, visit:

• HRL program website
• HRL science website

This repository

This repository contains code to render an overarching HRL science documentation website. The website is currently geared toward the data engineering and data science components of the HRL science program. Eventually, keystone HRL science documents, such as the HRL science plan, will also be provided as interactive web documents.

The HRL science documentation website contains information about:

• Data governance and management
• Core data science and data engineering commitments and standards
• Links to HRL program-wide templates and resources
• High-level workflows for data engineering and data science tasks
• Onboarding and learning materials
• Links to other HRL program resources

Technical details

This website is built using Quarto, a scientific and technical publishing system built on Pandoc. The website is rendered using GitHub Pages. We welcome suggestions for how this documentation website can be improved. Visit our contributing guidelines for more information on improving the HRL documentation website, and please note that contributors are expected to follow our code of conduct.

Rendering, freezing, and dependencies

• Quarto execution freezing is enabled globally (execute.freeze: auto in _quarto.yml). On render, Quarto saves cached computations for executable documents in the _freeze/ directory. Commit those cached outputs whenever you update rendered content so GitHub Actions can publish without re-running code.
• When you edit a .qmd file with executable code, re-run quarto render locally to refresh its _freeze artifacts. Quarto automatically re-executes any page whose source changed; untouched pages keep their cached results.
• If you need to force a rebuild of everything (for example, after updating packages), delete _freeze/ or run quarto render --no-cache before committing.
• R dependencies are managed with renv. After cloning the repo, run renv::restore() from R to install the packages pinned in renv.lock. When you add or update packages, use renv::install() / renv::snapshot() so the lockfile stays in sync. GitHub Actions automatically restores the renv environment before rendering.

With this workflow, everyday commits render locally with frozen outputs, and GitHub Actions simply republishes the already-computed site while remaining ready for future, more rigorous dependency management.

Agentic LLM usage for code generation

If you choose to use LLMs to assist with code generation for this repository, please be aware of the following:

• LLM instructions (functionally a system prompt) can be found in AGENTS.md.
• Always review and test any code generated by LLMs before committing it to ensure it functions as desired and meets the project's standards and requirements.
• Understand the lethal trifecta that can create critical LLM security vulnerabilities and ensure that your usage minimizes the potential for such risks.