first commit

.github/workflows/publish_site.yml

@@ -0,0 +1,36 @@
+on:
+  push:
+    branches: 
+      - main
+      - master
+
+name: Render & Publish Site
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+
+    env: 
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v2
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      - name: Render Site
+        run: |
+          quarto render
+
+      - name: No Jekyll
+        run: |
+          touch _site/.nojekyll
+
+      - name: Publish
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages
+          folder: _site
+          single-commit: true

.gitignore

@@ -0,0 +1,23 @@
+# Quarto files
+/.quarto/
+_site
+
+# python notebooks
+*.ipynb
+
+# R files
+.Rhistory
+.Rapp.history
+.RData
+.RDataTmp
+.Ruserdata
+.Rproj.user/
+*_cache/
+/cache/
+*.utf8.md
+*.knit.md
+.Renviron
+
+# Jupyter cache
+.jupyter_cache
+/.luarc.json

CITATION.cff

@@ -0,0 +1,36 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+# Note: we use the author alias to record author contributions
+# This is a known limitation of CFF files: https://github.com/citation-file-format/citation-file-format/issues/112
+
+cff-version: 1.2.0
+title: Course Development Guidelines
+message: >-
+  You may cite these materials using the metadata in this
+  file. Please cite our materials if you publish materials
+  derived from these, run a workshop using them, or use
+  the information in your own work.
+type: dataset
+authors:
+  - given-names: Hugo
+    family-names: Tavares
+    affiliation: Cambridge Centre for Research Informatics Training
+    website: 'https://bioinfotraining.bio.cam.ac.uk/staff/hugo-tavares-phd'
+    orcid: 'https://orcid.org/0000-0001-9373-2726'
+    alias: 'writing - original draft; conceptualisation; software'
+  - given-names: Martin
+    family-names: van Rongen
+    affiliation: Cambridge Centre for Research Informatics Training
+    orcid: 'https://orcid.org/0000-0002-1441-367X'
+    alias: 'writing - review & editing; conceptualisation; software'
+  - given-names: Alexia
+    family-names: Cardona
+    affiliation: Cambridge Centre for Research Informatics Training
+    orcid: 'https://orcid.org/0000-0002-7877-5565'
+    alias: 'conceptualisation'
+repository-code: 'https://github.com/cambiotraining/quarto-course-template'
+url: 'https://cambiotraining.github.io/quarto-course-template/'
+license: CC-BY-4.0
+commit: 3c8234e82c7315cfb4d869d9635433bf62baf17f
+date-released: '2024-08-23'

LICENSE.md

@@ -0,0 +1,29 @@
+The University of Cambridge Bioinformatics Training Facility releases these training materials under the Creative Commons Attribution license.
+
+----
+
+This is a human-readable summary of (and not a substitute for) the [full legal text of the CC BY 4.0 license](https://creativecommons.org/licenses/by/4.0/legalcode).
+
+## You are free to:
+
+- **Share** - copy and redistribute the material in any medium or format
+- **Adapt** - remix, transform, and build upon the material for any purpose, even commercially.
+
+The licensor cannot revoke these freedoms as long as you follow the license terms.
+
+
+## Under the following terms:
+
+- **Attribution** - You must give appropriate credit (by providing the name of the authors of these materials, citing the work as indicated in the course homepage and linking to the course website), provide a [link to the license](https://creativecommons.org/licenses/by/4.0/), and indicate if changes were made. 
+  You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
+
+- **No additional restrictions** - You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+
+## Notices:
+
+You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
+
+No warranties are given. 
+The license may not give you all of the permissions necessary for your intended use. 
+For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

README.md

@@ -0,0 +1,8 @@
+# Course Name
+
+This repository contains the materials for the course.
+
+**Course Developers**: see our [guidelines page](https://cambiotraining.github.io/quarto-course-template/materials.html) if contributing materials.
+
+These materials are released under a [CC BY 4.0](LICENSE.md) license.
+

_extensions/cambiotraining/courseformat/_extension.yml

@@ -0,0 +1,17 @@
+title: Course Page Format
+author: Cambridge Informatics Training
+version: 1.2.1
+contributes:
+  formats:
+    html:
+      theme: [default, theme.scss]
+      toc: true
+      number-sections: true
+      number-depth: 3
+      code-link: true
+      code-copy: true
+  shortcodes:
+    - star_levels.lua
+    - citation_cff.lua
+  filters:
+    - callout_exercise.lua

_extensions/cambiotraining/courseformat/callout_exercise.lua

@@ -0,0 +1,129 @@
+local number_exercises = true
+local hide_answers = false
+local exercises = {}  -- Table to store exercise IDs and titles
+local exercise_counter = 0  -- Global counter for exercises
+local seen_ids = {}  -- Table to track seen IDs and check for duplicates
+
+-- function to throw a yellow warning
+function warn(message)
+  local yellow = "\27[33m"
+  local reset = "\27[0m"
+  io.stderr:write(yellow .. "WARN: " .. message .. reset .. "\n")
+end
+
+-- Meta function to read yml metadata
+function Meta(meta)
+  if meta["exercises"] and meta["exercises"]["number"] == true then
+    number_exercises = true
+  end
+
+  if meta["exercises"] and meta["exercises"]["hide-answers"] == true then
+    hide_answers = true
+  end
+end
+
+-- Div function to process exercises and answers
+function Div(div)
+  -- Process callout-exercise divs
+  if div.classes:includes("callout-exercise") then
+    exercise_counter = exercise_counter + 1
+    local exercise_number = "Exercise " .. exercise_counter  -- Always generate the number
+
+    -- Store exercise ID and title if it has an ID starting with "ex-"
+    if div.identifier and div.identifier:match("^ex%-") then
+      -- Check for duplicate IDs
+      if seen_ids[div.identifier] then
+        warn("Duplicate exercise ID found: #" .. div.identifier)
+      end
+
+      seen_ids[div.identifier] = true
+      exercises[div.identifier] = exercise_number
+    end
+
+    -- Process the header within the exercise
+    if div.content[1] ~= nil and div.content[1].t == "Header" then
+      local title = pandoc.utils.stringify(div.content[1])
+      div.content:remove(1)  -- Remove the original header from content
+      local final_title = number_exercises and exercise_number .. " - " .. title or title
+      return quarto.Callout({
+        type = "exercise",
+        content = { div },
+        title = final_title,
+        icon = false,
+        collapse = false
+      })
+    else
+      -- If no header, use just the exercise number (if numbering is on)
+      local final_title = number_exercises and exercise_number or nil
+      return quarto.Callout({
+        type = "exercise",
+        content = { div },
+        title = final_title,
+        icon = false,
+        collapse = false
+      })
+    end
+  end
+
+  -- Process callout-answer divs
+  if div.classes:includes("callout-answer") then
+    if (hide_answers and div.attributes["hide"] ~= "false") or div.attributes["hide"] == "true" then
+      return pandoc.RawBlock('html', '<div hidden></div>')
+    else
+      return quarto.Callout({
+        type = "answer",
+        content = { div },
+        title = "Answer",
+        icon = false,
+        collapse = true
+      })
+    end
+  end
+
+  -- Process callout-hint divs
+  if div.classes:includes("callout-hint") then
+    return quarto.Callout({
+      type = "hint",
+      content = { div },
+      title = "Hint",
+      icon = false,
+      collapse = true
+    })
+  end
+end
+
+-- Replace cross-references in Pandoc elements
+function Pandoc(doc)
+  -- Walk through the document and replace any Str element that matches @ex-*
+  local function replace_xref(elem)
+    if elem.t == "Str" and elem.text:match("^@ex%-") then
+      local id = elem.text:sub(2)  -- Remove the "@" prefix
+      local exercise_title = exercises[id]
+      if exercise_title then
+        -- Return the custom HTML link
+        local link_html = string.format(
+          '<a href="#%s"><u>%s</u></a>',
+          id,
+          exercise_title
+        )
+        return pandoc.RawInline('html', link_html)
+      else
+        -- If the ID is not found, throw a warning
+        warn("Undefined exercise cross-reference: @" .. id)
+      end
+    end
+    return elem
+  end
+
+  -- Apply the replacement to all inline elements
+  return doc:walk({
+    Str = replace_xref
+  })
+end
+
+-- Return the filter
+return {
+  { Meta = Meta },
+  { Div = Div },
+  { Pandoc = Pandoc }
+}