tusk

Source for the Roberts Lab course set — https://robertslab.github.io/tusk/

The intent is to offer core, basic content. What that exactly might be could be complicated, but let's start very basic / foundational and work our way up.

The site has two kinds of content:

• Modules — hands-on technical training, ordered so that each one builds on the ones before it, but written so any single module also stands alone.
• Lab Science — the lab's conceptual grounding: how we define environmental memory and resilience, and the foundational papers that framing is distilled from.

Repository layout

_quarto.yml            site config — navbar, sidebar, theme
index.qmd              landing page
about.qmd              about / contributing pointer
styles.css             site-wide CSS overrides
modules/               numbered training modules (00–05)
  04-data/             inputs + outputs for the BLAST module
framework/             Lab Science pages
  papers/              openly licensed PDFs served from the site
docs/                  RENDERED SITE — committed, served by GitHub Pages
_site/                 stale output from an older config; not used

docs/ is the published site. GitHub Pages serves it directly from main, which means rendered output has to be committed along with your source changes or the live site will not update. The .nojekyll files stop Pages from trying to run Jekyll over the Quarto output.

Building locally

You need:

• Quarto 1.7 or newer
• R, plus the knitr package — the modules use {r} code chunks, so Quarto renders through knitr rather than treating them as plain markdown

Then, from the repo root:

quarto preview

That serves the site locally and live-reloads as you edit. When you're ready to publish:

quarto render

This writes to docs/. Commit the source and the docs/ changes together.

Heads up on modules/04-blast.qmd: several of its chunks are still eval=TRUE, so rendering it downloads reference data and actually runs makeblastdb / blastx into modules/04-data/. You need NCBI BLAST+ on your PATH, and a full render takes a few minutes. If you only touched an unrelated page, render just that file — quarto render index.qmd — instead of the whole site.

Note also that rendering with a newer Quarto than the last contributor used will rewrite everything under docs/site_libs/. That churn is expected and harmless; it just makes the diff noisy.

Contributing

Issues, corrections, and new content are all welcome. Every page has Edit this page and Report an issue links in the right margin for small fixes.

For anything larger, branch off main, make the change, render, and open a pull request.

Adding a module

1. Create modules/NN-shortname.qmd, continuing the number sequence. The number sets reading order.

2. Give it front matter with a short, human-readable title — this is the text that shows up in the sidebar:

   ---
   title: "NCBI Blast"
   subtitle: "Taking a set of unknown sequence files and annotating them"
   ---

3. Register it in _quarto.yml under the Modules section of sidebar: contents:. A file that isn't listed there renders but is unreachable from the site navigation — this is the most common thing to forget.

4. Render and commit.

Writing guidelines

• Assume the reader is new to the tool. Explain the why before the how.
• Prefer showing real commands with real output over describing them in prose.
• Keep code chunks reproducible. If a chunk depends on data or software a reader won't have, set eval=FALSE and show the expected output as a static block instead.
• Don't commit large data files. data/ is git-ignored; use it for scratch inputs and outputs.

A note on the papers

framework/papers/ only holds PDFs that carry an open license (CC BY / CC BY-NC), because everything in docs/ is publicly served. Paywalled papers are cited by DOI only. Please keep it that way when adding references — check the paper's license before committing a PDF.

Questions

Open an issue at https://github.com/RobertsLab/tusk/issues.