ucospo.net

The UC OSPO Network website, built with MyST.

Prerequisites

• Node.js v20+ and npm
• Python 3.10+ (optional, for pre-commit hooks)

Local development

1. Clone the repo

git clone git@github.com:UC-OSPO-Network/ucospo.net.git
cd ucospo.net

2. Install dependencies

npm install

3. (Optional) Set up pre-commit hooks

Pre-commit hooks run Prettier, markdownlint, Black, and codespell automatically before each commit. To enable them, first create a Python virtual environment and install the hook:

python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pre-commit install

If you skip this step, the pre-commit.ci bot will check your PR automatically instead.

4. Preview the site

make serve
# or: npx myst start

This starts a live-reload dev server, typically at http://localhost:3000.

5. Build a static copy

make html
# or: npx myst build --html

Output goes to _build/html/.

Project structure

myst.yml          # site config and table of contents
index.md          # home page
about.md          # about page
news.md           # news page
campus/           # per-campus pages
events/           # event pages
guiding-themes/   # guiding themes section
oss-resources/    # open source resource guides
posts/            # blog posts
static/          # images, CSS, and other static assets

Content conventions

• Pages are MyST Markdown.
• The table of contents is defined in myst.yml under project.toc. Add new pages there as well as creating the .md file.
• Blog post frontmatter uses tags as an array: tags: [tag1, tag2].
• Admonitions use MyST syntax: :::{note}, :::{tip}, :::{important}.

Linting and formatting

This project uses pre-commit with:

• Prettier — auto-formats Markdown, CSS, and YAML
• markdownlint — checks Markdown structure and accessibility (heading levels, alt text, informative link text, etc.). Configuration is in .markdownlint-cli2.yaml.
• Black — Python code formatting
• codespell — catches common typos

If you push without running pre-commit locally, the pre-commit.ci bot will check your PR automatically. See CONTRIBUTING.md for usage details.

Contributing

See CONTRIBUTING.md for the full contribution workflow including forking, branching, and the PR review process.