Update tutorial structure

.filenameignore

@@ -0,0 +1,24 @@
+# Paths to ignore for filename/path validation checks.
+# Patterns use fnmatch syntax and are relative to repo root.
+
+_site/**
+.quarto/**
+.github/**
+_extensions/
+
+# Common documentation files to ignore
+LICENSE-CODE.md
+LICENSE.md
+LICENSE
+README.md
+README
+README-template.md
+CITATION.cff
+CITATION-template.cff
+_quarto.yml
+404.qmd
+
+# exceptions
+assets/
+hallgren-2013
+ihle-2020

.github/workflows/README.md

@@ -0,0 +1,76 @@
+# Workflows (GitHub Actions)
+
+This document explains the GitHub Actions workflows in `.github/workflows/` in beginner-to-intermediate friendly language: what each workflow does, how it is triggered, and what is essential to keep working.
+
+## Quick summary
+
+- Location: `.github/workflows/`
+- How to run: workflows run automatically on `push` to `main`, on a schedule, or manually via the **Actions** tab → "Run workflow" (if `workflow_dispatch` is enabled).
+
+---
+
+## Individual workflows
+
+### citation-check.yml — Validate `CITATION.cff`
+
+- Purpose: Validate the project's `CITATION.cff` so metadata (authors, ORCID, affiliations) is well-formed and machine-readable.
+- Triggers: `push` to `main` when `CITATION.cff` changes, and manual runs (`workflow_dispatch`).
+- What it does: checks out the repo and runs `dieghernan/cff-validator@v3`.
+- Essentials to keep: the `Checkout` step and the validator step. No extra secrets are required.
+- Tips: safe to update the validator action version; don't remove checkout.
+
+### filename-check.yml — Enforce filename rules
+
+- Purpose: Ensure file and path names meet limits (length, depth, allowed extensions) to prevent publishing problems.
+- Triggers: `push` to `main`, `pull_request`, and manual runs.
+- What it does: uses `NeuroShepherd/check-filenames-action@v1` with inputs such as `max-path-length`, `max-depth`, and allowed `file-types`. It may respect a `.filenameignore` file when present.
+- Essentials to keep: the check-filenames action and its configuration inputs.
+- Tips: adjust `max-path-length`/`max-depth` or add `.filenameignore` entries if legitimate files are flagged.
+
+### publish.yaml — Render and publish the Quarto site
+
+- Purpose: Build the Quarto site and publish the rendered site to the `gh-pages` branch.
+- Triggers: `push` to `main`, weekly schedule (cron), and manual runs.
+- What it does (high-level): checks out code, installs Quarto, installs system and R dependencies as needed, renders the site, and publishes to `gh-pages` using `quarto-actions/publish@v2`.
+- Essentials to keep:
+	- `quarto-dev/quarto-actions/setup@v2` (Quarto install)
+	- the render and publish step (`quarto-actions/publish@v2`)
+	- repository permission for `contents: write` to allow publishing
+- Notes:
+	- If you use R, the workflow detects `renv.lock` and restores packages; include `renv.lock` for reproducible builds.
+	- The workflow installs system libraries via `apt` (image handling, PDF, and some R packages require these). Remove packages only if you understand the consequences.
+- Common edits: change schedule timing or branch triggers. Removing the publish step disables automatic deployment.
+
+### style.yaml — Format R/QMD code using `styler`
+
+- Purpose: Automatically format R and Quarto/R Markdown code using `styler::style_dir()` and optionally commit formatted code.
+- Triggers: currently manual (`workflow_dispatch`) — push triggers are commented out.
+- What it does: installs R and `styler`, runs `styler::style_dir()`, and if files were reformatted the workflow commits and pushes changes using `GITHUB_TOKEN`.
+- Essentials to keep: the style run and cache steps; the commit step is optional depending on whether you want automatic changes.
+- Tips: to avoid unexpected commits, run manually or restrict to PR checks instead of auto-committing.
+
+---
+
+## Quick guidance — what to change vs what to leave alone
+
+- Safe to change:
+	- Schedules and branch triggers
+	- Input limits for checks (e.g., filename length, allowed file types)
+	- Action versions (bump to newer versions)
+- Be careful editing:
+	- The `publish` workflow's render/publish steps — removing them will stop site builds and deployment.
+	- System dependency installation (`apt` lines) used by rendering and some R packages.
+	- The auto-commit logic in `style.yaml` if you don't want automatic pushes. That is this workflow only runs on `workflow_dispatch` meaning it currently can only be manually triggered in Actions.
+
+## How to run workflows manually
+
+- In GitHub: Open the repository → **Actions** tab → choose a workflow → click **Run workflow** (if available).
+- Locally: To test Quarto rendering locally, use `quarto preview` or `quarto render` in your project directory.
+
+## Where to look for failures
+
+- Open the **Actions** tab in GitHub, select the workflow run, and inspect step logs to see errors and stack traces.
+
+---
+
+

.github/workflows/citation-check.yml

@@ -0,0 +1,21 @@
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    paths:
+    - CITATION.cff
+
+name: Check CITATION.cff is Valid
+jobs:
+  Validate-CITATION-cff:
+    runs-on: ubuntu-latest
+    name: Validate CITATION.cff
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Validate CITATION.cff
+        uses: dieghernan/cff-validator@v3

.github/workflows/filename-check.yml

@@ -0,0 +1,22 @@
+name: Filename Checks
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check-names:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check filenames
+        uses: NeuroShepherd/check-filenames-action@v1
+        with:
+          max-path-length: "65"
+          max-depth: "2"
+          file-types: "html,md,qmd,css,scss,rmd,pdf,png,jpg,svg,yml"
+          ignore-file: ".filenameignore"
+          dotfile-mode: "strip-leading-dot"

.github/workflows/link-checker.yml

@@ -0,0 +1,44 @@
+name: Link Checker
+
+on:
+  schedule:
+    - cron: '0 0 1 * *'
+  workflow_dispatch:
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Check links
+        id: check
+        uses: filiph/linkcheck@master
+        continue-on-error: true
+        with:
+          arguments: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/
+
+      - name: Create issue on broken links
+        if: steps.check.outputs.exit_code != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = fs.readFileSync('log', 'utf8');
+
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              labels: 'link-checker'
+            });
+
+            if (issues.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                title: '🔗 Broken Links Found on Site',
+                body: `The monthly link checker detected broken links.\n\n${report}`,
+                labels: ['link-checker']
+              });
+            }

.github/workflows/publish.yaml

@@ -1,12 +1,14 @@
 on:
   workflow_dispatch:
+  schedule:
+    - cron: "0 23 * * 0"
   push:
-    branches: main
+    branches: [main]
 
-name: Quarto Publish
+name: Render Quarto Site
 
 jobs:
-  build-deploy:
+  quarto-publish:
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -16,16 +18,85 @@ jobs:
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          tinytex: true
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt install -y \
+            libcurl4-openssl-dev \
+            libfontconfig1-dev \
+            libssl-dev \
+            libxml2-dev \
+            libpng-dev \
+            libjpeg-dev \
+            libtiff-dev \
+            libcairo2-dev \
+            libxt-dev \
+            libfreetype6-dev \
+            libharfbuzz-dev \
+            libfribidi-dev \
+            zlib1g-dev \
+            libv8-dev \
+            libglpk-dev \
+            librsvg2-bin
 
-      - name: Install R
+      - name: Install R with renv
         uses: r-lib/actions/setup-r@v2
         with:
-          r-version: '4.4.0'
+          r-version: renv
+        if: ${{ hashFiles('renv.lock') != '' }}
 
-      - name: Install R Dependencies
+      - name: Install R Dependencies with renv
         uses: r-lib/actions/setup-renv@v2
         with:
           cache-version: 1
+        if: ${{ hashFiles('renv.lock') != '' }}
+
+      - name: Install R latest
+        uses: r-lib/actions/setup-r@v2
+        if: ${{ hashFiles('renv.lock') == '' }}
+
+      - name: Set R library path (no lockfile)
+        run: echo "R_LIBS_USER=$HOME/.local/lib/R/site-library" >> "$GITHUB_ENV"
+        if: ${{ hashFiles('renv.lock') == '' }}
+
+      - name: Cache R library (no lockfile)
+        uses: actions/cache@v4
+        with:
+          path: ~/.local/lib/R/site-library
+          key: ${{ runner.os }}-r-nolock-${{ hashFiles('**/*.R', '**/*.Rmd', '**/*.qmd', '_quarto.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-r-nolock-
+        if: ${{ hashFiles('renv.lock') == '' }}
+
+      - name: Install R latest dependencies
+        run: |
+          lib <- Sys.getenv("R_LIBS_USER")
+          if (nzchar(lib)) {
+            dir.create(lib, recursive = TRUE, showWarnings = FALSE)
+            .libPaths(c(lib, .libPaths()))
+          }
+          install.packages("renv")
+          install.packages("rmarkdown")
+          install.packages("yaml")
+          deps <- unique(stats::na.omit(renv::dependencies()$Package))
+          if (length(deps) > 0) install.packages(deps)
+        shell: Rscript {0}
+        if: ${{ hashFiles('renv.lock') == '' }}
+
+      - name: Ensure Quarto R runtime packages
+        run: |
+          lib <- Sys.getenv("R_LIBS_USER")
+          if (nzchar(lib)) {
+            dir.create(lib, recursive = TRUE, showWarnings = FALSE)
+            .libPaths(c(lib, .libPaths()))
+          }
+          pkgs <- c("knitr", "rmarkdown")
+          missing <- pkgs[!vapply(pkgs, requireNamespace, logical(1), quietly = TRUE)]
+          if (length(missing) > 0) install.packages(missing)
+        shell: Rscript {0}
 
       - name: Render and Publish
         uses: quarto-dev/quarto-actions/publish@v2

.github/workflows/style.yaml

@@ -0,0 +1,27 @@
+on:
+  workflow_dispatch:
+
+name: Air Formatting
+
+permissions:
+  contents: write
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install Air
+        uses: posit-dev/setup-air@v1
+
+      - name: Format
+        run: air format .
+
+      - name: Commit and push changes
+        uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: "Style code (Air)"

.github/workflows/update-extension.yml

@@ -0,0 +1,32 @@
+name: Update Tutorial Template Extension
+
+on:
+  schedule:
+    - cron: "0 0 2 * *"
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  update-downstream-tutorials:
+    # prevent action from running in actual extension repo--else, recursive installations
+    # only users of the extension should have these auto-updates
+    if: github.repository != 'lmu-osc/tutorial-template'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Update tutorial-template extension
+        run: quarto update lmu-osc/tutorial-template --no-prompt
+
+      - uses: stefanzweifel/git-auto-commit-action@v7
+        with:
+          commit_message: "Update tutorial-template extension (GHA)"

.gitignore

@@ -58,3 +58,9 @@ rsconnect/
 .httr-oauth
 .quarto
 _site/
+**_files/
+
+**/*.quarto_ipynb
+
+# ignore posi assistant settings
+.posit/assistant

404.qmd

@@ -0,0 +1,14 @@
+---
+title: Uh-oh, looks like the page is missing!
+description: The page you are looking for cannot be found 😟
+---
+
+The page you are looking for either does not exist or has been moved. Please check the URL and try again. If you believe this is an error, please contact the website administrator for assistance.
+
+Note: many pages within our old tutorials have been moved to new locations as part of standardization efforts. It's likely the page you are looking for has been moved to a new location within the site.
+
+<!-- 
+Note: if you, the developer, want to have custom messages based on the URL someone is trying to access e.g. because a popular page has been moved and you want to direct readers to the new page/section, take a look at the `404.qmd` file in the main OSC website: https://github.com/lmu-osc/lmu-osc.github.io/blob/main/404.qmd
+
+It contains code with customized messages/information based on the URL path that is being accessed. You can adapt this code to your own needs and customize the messages as you see fit.
+ -->