Skip to content

Contributing

We welcome contributions from lab members and the community!

Repository

How to Contribute

  1. Report Issues: Use GitHub Issues to report errors, request new protocols, or suggest improvements.
  2. Submit Changes:
    • Fork the repository
    • Create a branch: git checkout -b feature/my-improvement
    • Make your changes
    • Commit: git commit -m 'Add protocol for X'
    • Push: git push origin feature/my-improvement
    • Open a Pull Request

Local Development

# 1. Clone and setup
git clone https://github.com/HuangLab-PKU/spatial-workshop.git
cd spatial-workshop
mamba env create -f environment.yml
mamba activate spatial-workshop

# 2. Local dev server (hot reload)
mkdocs serve --livereload
# Open http://127.0.0.1:8000/

# 3. Build public site
mkdocs build

# 4. Build private site (includes lab/ content)
mkdocs build -f mkdocs-private.yml

Deployment

Both builds are hosted on Cloudflare Pages — see DEPLOY-PRIVATE.md (repo root) for the full runbook.

Target Build Visibility
Public mkdocs build (excludes docs/lab/) Open
Private mkdocs build -f mkdocs-private.yml (includes docs/lab/) Behind Cloudflare Access

Both rebuild on push to main. Docker (docker-compose up, localhost:8080) is optional local preview of the private build only.

Writing Guidelines

  • Language: English for all documentation. Chinese translations go in docs/zh/ (mirror structure).
  • Format: Markdown (MkDocs Material extensions available).
  • Protocols: Preserve version headers; keep step numbering consistent; use admonitions for warnings/tips.
  • Images: Place in docs/assets/images/ with descriptive names.

The metadata block

Every protocol and reagent page opens with the same block, directly under the H1, in this order and with no other fields:

# Page Title

- **Applicable samples:** ...        <- protocols only; omit on reagent pages
- **Version:** vX.Y
- **Last modified:** YYYY-MM-DD

hooks/protocol_index.py parses Version and Last modified from here to build the protocol inventory on the Lab Private overview, so the format is load-bearing — a page that drifts silently drops out of the index.

Three rules that come from past drift:

  • No Author field. Git records authorship; a per-page byline only goes stale.
  • No Purpose field. That is what the frontmatter description and the opening paragraph are for.
  • Version must match the newest ## Changelog entry, and the frontmatter version: if the page has one. scripts/check_protocols.py enforces both.

Background pages under docs/shared/ and index/overview pages carry no metadata block — they are not versioned artefacts.

Project Structure

docs/
├── technologies/    # Technology overviews (PRISM, SPRINTseq, probe design)
├── prism/           # PRISM-specific pages
├── sprintseq/       # SPRINTseq-specific pages
├── protocols/       # Step-by-step SOPs
├── reagents/        # Reagent preparation guides
├── shared/          # Shared background (RCA mechanism, imaging)
├── resources/       # BOM, FAQ, datasets, gallery
├── about/           # Team, citation, contributing
├── lab/             # Private-only drafts (excluded from public build)
└── zh/              # Chinese translations (mirrors English structure)
Ask / Feedback