From 4643b9bce1b5813a43e212304bb334ac5619034e Mon Sep 17 00:00:00 2001 From: David Jose Sao Date: Thu, 18 Jun 2026 17:28:10 +1000 Subject: [PATCH 01/24] Forked New Repo, Created spec for cleaning --- SPEC.md | 434 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ book.toml | 12 +- 2 files changed, 441 insertions(+), 5 deletions(-) create mode 100644 SPEC.md diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 0000000..0cf879c --- /dev/null +++ b/SPEC.md @@ -0,0 +1,434 @@ +# Workshop Handbook Template — Implementation Spec + +## Goal + +Turn the forked **2025 CompClub Spring Handbook** into a generic **`workshop-handbook-template`** repo that new workshops can copy or fork. Strip event-specific content, ship a **ready-to-use starter template**, and document how teams can customize further based on their preferences. + +## Stakeholder sign-off + +## Locked decisions + +| Area | Decision | +|------|----------| +| **Starter template** | **Include a full starter template** — not an empty repo. Ship placeholder chapters, example pages, and docs so authors can fork and start writing immediately. | +| **Theme** | **Neutral built-in mdBook theme by default** (`coal`). No custom/pirate styling active out of the box. Teams change `default-theme` or add custom CSS **based on preference** — not required. | +| **Answer widgets** | **Keep one documented example page** (`src/examples/answer-widget.md`) with shared CSS in active `theme/custom.css`. | +| **`site-url`** | **Placeholder** (`/YOUR-REPO-NAME/`) in template + README checklist. Canonical repo uses real value (`/Workshop-handbook-template/`). CI auto-set = follow-up ticket. | + +--- + +## Scope + +### In scope (this ticket) + +- Generic `book.toml` metadata and Pages config +- mdbook-callouts preprocessor config +- **Starter template content** in `src/` (intro + example chapters — see §3) +- Neutral default theme with minimal `custom.css` (callouts + answer widgets only) +- Optional custom theme example archived under `theme/examples/` (preference-based, not default) +- Rewrite README with setup, deploy, and customization docs +- Fix and verify GitHub Actions Pages deploy workflow +- Remove all CompClub / 2025 Spring / SecSoc references + +### Out of scope (follow-up tickets) + +- CI step to auto-set `site-url` from `github.repository` +- mdBook preprocessor/plugin for answer widgets (replace inline JS) +- Contributing guidelines, issue templates, org-wide naming policy +- Prescribing a specific brand/theme for all workshops + +--- + +## What "include a template" means + +The repo must ship **working starter content**, not just config files. A workshop lead should be able to: + +1. Fork the repo +2. Run `mdbook serve --open` +3. See a complete (if minimal) handbook with navigation, callout examples, and an answer-widget demo +4. Replace placeholder text and add their own chapters + +### Starter template contents + +| Item | Purpose | +|------|---------| +| `src/main.md` | Welcome page + quick-start instructions | +| `src/SUMMARY.md` | Navigation skeleton teams extend | +| `src/examples/callouts.md` | Live callout reference | +| `src/examples/answer-widget.md` | Interactive exercise pattern | +| `book.toml` | Pre-configured with placeholders teams replace | +| `theme/custom.css` | Minimal shared styles (callouts + widgets) | +| `README.md` | Fork setup checklist + customization guide | +| `.github/workflows/mdbook.yml` | Deploy pipeline ready to go | + +Teams delete or replace example pages as they write real workshop content. The template is a starting point, not the final product. + +--- + +## Target repo structure + +``` +workshop-handbook-template/ +├── .github/workflows/mdbook.yml +├── .gitignore +├── README.md +├── SPEC.md +├── book.toml +├── src/ +│ ├── SUMMARY.md +│ ├── main.md +│ └── examples/ +│ ├── callouts.md +│ └── answer-widget.md +└── theme/ + ├── custom.css # active: callouts + answer widgets only + └── examples/ + └── pirate/ # optional — enable based on preference + ├── README.md + ├── custom.css + ├── variables.css + └── index.hbs +``` + +**Remove entirely:** + +- `src/ciphers/` +- `src/2_breaking_game_saves/` +- `src/3_day_3_web_attacks/` +- `src/images/` (empty or workshop-specific) +- `src/topic` + +**Remove from active `theme/`** (relocate to `theme/examples/pirate/` or delete): + +- `theme/index.hbs` +- `theme/book.js` +- `theme/css/` +- `theme/fonts/` +- `theme/highlight.css` +- `theme/highlight.js` +- `theme/favicon.png` (optional: keep one neutral favicon or drop) + +--- + +## 1. `book.toml` + +```toml +[book] +title = "Workshop Handbook" +author = "Your Organization" +language = "en" +description = "A template for workshop handbooks built with mdBook." + +[build] +build-dir = "book" + +[output.html] +default-theme = "coal" +site-url = "/YOUR-REPO-NAME/" +git-repository-url = "https://github.com/YOUR-ORG/YOUR-REPO-NAME" +additional-css = ["theme/custom.css"] + +[preprocessor.callouts] +``` + +**Canonical repo override** (document in README, apply in `davidjosesao/Workshop-handbook-template`): + +```toml +site-url = "/Workshop-handbook-template/" +git-repository-url = "https://github.com/davidjosesao/Workshop-handbook-template" +``` + +**Notes:** + +- `default-theme = "coal"` — neutral built-in theme. Do not ship a custom theme as default. +- `[preprocessor.callouts]` with no extra keys is sufficient for mdbook-callouts v0.3.x. +- `git-repository-url` powers the repo icon in the menu bar. + +--- + +## 2. Theme + +### Principle + +**Default = neutral. Customization = optional preference.** + +The template must look clean and professional out of the box using mdBook's built-in themes. No workshop is required to adopt custom branding. + +### 2a. Active default: built-in theme + `theme/custom.css` + +- Use stock mdBook templates (no active `theme/index.hbs` override). +- `default-theme = "coal"` in `book.toml`. +- Active `theme/custom.css` contains **only** shared utility styles: + +**Include:** + +- mdbook-callouts CSS variables on `:root` +- `.answer-box`, `.answer-input`, `.answer-button`, `.correct`, `.incorrect` (neutral colors) + +**Exclude:** + +- Google Fonts imports +- All `.scifi` / pirate rules +- `ship-background.png` references +- Any opinionated branding + +**Example structure:** + +```css +/* Callouts — work across built-in themes */ +:root { + --mdbook-callouts-background: …; + --mdbook-callouts-border: …; +} + +/* Interactive answer widgets */ +.answer-box { … } +``` + +### 2b. Customization options (document in README — preference-based) + +Teams choose what fits their workshop. None of this is required. + +| Preference | How | +|------------|-----| +| Different built-in theme | Change `default-theme` in `book.toml` to `light`, `rust`, `navy`, or `ayu` | +| Light style tweaks | Edit `theme/custom.css` | +| Full custom branding | See `theme/examples/pirate/README.md` for an archived example from the original handbook | + +### 2c. Archived optional example: `theme/examples/pirate/` + +The original CompClub pirate theme is **not the default**. Archive it as a reference for teams who want heavy customization. + +| File | Source | Purpose | +|------|--------|---------| +| `custom.css` | Current `theme/custom.css` | Full pirate look | +| `variables.css` | Current `theme/css/variables.css` (`.scifi` block) | Theme tokens | +| `index.hbs` | Current `theme/index.hbs` | Custom theme menu entry | +| `README.md` | New | Opt-in instructions | + +**`theme/examples/pirate/README.md` should explain:** + +1. This is an **optional example**, not the template default. +2. How to copy files and enable the custom theme if desired. +3. Set `default-theme = "scifi"` when using this example's CSS. +4. `ship-background.png` is not bundled — add your own or remove background rules. +5. Built-in themes (`coal`, `navy`, etc.) are the recommended starting point for most workshops. + +### 2d. Drop active full theme override + +With only `theme/custom.css` referenced, mdBook uses **built-in** templates from the `mdbook` binary. + +**Do not** leave a partial `theme/index.hbs` in the active path. + +--- + +## 3. Content (`src/`) + +### 3a. Delete workshop chapters + +Remove all CompClub curriculum (~30 files). No CompClub slide links, cipher puzzles, or "DAY 1 / DAY 3" structure in the template. + +### 3b. `src/SUMMARY.md` + +```markdown +# Summary + +- [Introduction](main.md) +- [Examples](examples/callouts.md) + - [Answer widgets](examples/answer-widget.md) +``` + +### 3c. `src/main.md` + +Starter template landing page covering: + +- What this repo is and that it's a **template to fork and customize** +- Quick start: `cargo install mdbook mdbook-callouts`, `mdbook serve --open` +- How to add a chapter (create `.md`, link in `SUMMARY.md`) +- Pointer to `examples/` for callouts and answer widgets +- How to change theme (built-in options in `book.toml`) +- **First deploy checklist** (see README) +- One sample callout + +### 3d. `src/examples/callouts.md` + +Live reference for supported callout types: + +- `INFO`, `NOTE`, `TIP`, `WARNING`, `ERROR`, `QUOTE`, `SUCCESS` (or whatever mdbook-callouts supports) +- Link to https://crates.io/crates/mdbook-callouts + +### 3e. `src/examples/answer-widget.md` + +Single minimal interactive example: + +- One question + one answer box +- Inline ` diff --git a/src/ciphers/5_vigenere_ciphers.md b/src/ciphers/5_vigenere_ciphers.md deleted file mode 100644 index bb2ea8d..0000000 --- a/src/ciphers/5_vigenere_ciphers.md +++ /dev/null @@ -1,24 +0,0 @@ -# 🧩 Vigenere Ciphers 🧩 - -A Vigenere Cipher is like a substitution cipher, except that we use a different rotation for every letter. - -Usually these are based off a phrase or word. - -## Try encrypting/decrypting - -Vigenere Cipher encryption/decryption - -> [!TIP] Breaking Vigenere ciphers tips -> - It's really hard! -> - We won't be covering much breaking of them, but feel free to try the following if you have time. -> - Try using techniques from substitution ciphers, with the knowledge that the keys are four letters long. - - -## Examples - -Attempt if you dare! - -1. G xuzc fa vm fa rmybrjgn lmdwhfabh yzp wyhq usz! Fwge ytqemvc ue hsbqg jazv ra majai icotcgcgtq. -2. O pir ibcrz gw xka! Wrk ges zuzik swyx sqzk fqb yrdit rqkng vmtr bit. - - diff --git a/src/ciphers/6_base_64.md b/src/ciphers/6_base_64.md deleted file mode 100644 index 85fb5ee..0000000 --- a/src/ciphers/6_base_64.md +++ /dev/null @@ -1,35 +0,0 @@ -# 🤖 Base 64 🤖 - -Base 64 is an encoding scheme for text and binary data. -We write out our input as binary data, group it into groups of six bits, and then use a Base 64 alphabet to write it down. - -If you're curious, here's the whole alphabet! -``` -ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/ -``` - -If the input does not cleanly fit into 6 bit groups, we add `=` at the end for padding. - -## Why? - -Allows us to encode arbitrary binary data as printable text! Very useful for e.g. sending it over the web. - -## Example - -``` -I <3 Compclub! -``` -is -``` -01001001 00100000 00111100 00110011 00100000 01000011 01101111 01101101 01110000 01100011 01101100 01110101 01100010 00100001 -``` -in Binary. - -Group into groups of six: -``` -010010 010010 000000 111100 001100 110010 000001 000011 011011 110110 110101 110000 011000 110110 110001 110101 011000 100010 0001 -``` -Convert to Base 64 Alphabet: -``` -SSA8MyBDb21wY2x1YiE= -``` diff --git a/src/ciphers/caesar_cipher.md b/src/ciphers/caesar_cipher.md deleted file mode 100644 index 1652b20..0000000 --- a/src/ciphers/caesar_cipher.md +++ /dev/null @@ -1,75 +0,0 @@ -# 🔒 CAESAR CIPHER 🔒 -The Caesar cipher is a substitution cipher where each letter in the plaintext is shifted by a fixed number of places down the alphabet. - -## How It Works -- Choose a shift value (e.g., 3). -- Replace each letter with the letter that is `shift` positions down the alphabet. -- Wrap around to the beginning of the alphabet if necessary. -- USE YOUR CIPHER WHEEL! - -## Decrypting Caesar Ciphers -> [!SUCCESS] Task -> Decrypt the following ciphers. Note that **punctuation matters** when inputting your answers. Upper and lower case does not matter. -> -> The following all use a Caesar cipher with different shift values. - -### Cipher 1 -Y qcapcr kcqqyec uyq upgrrcl ml rfc uyjjq md rfc aytcpl, uygrgle dmp qmkcmlc ajctcp clmsef rm qmjtc gr. - - -
- - -
- -
- -### Cipher 2 -Oek adem jxqj vuubydw oek wuj mxud oekhu ijqdtydw yd q xywx fbqsu... ikttud khwu je zkcf?... Y tedj xqlu yj. - Sqfjqyd Zqsa Ifqhhem. - - -
- - -
- -
- -### Cipher 3 -Liztqvo, pwtl ug pivl. Vwbpqvo jmiba i Rmb bew pwtqlig, ivl zqopb vwe gwc kiv aidm nqnbg xwcvla xmz xmzawv. Bpiba bew pcvlzml xwcvla wnn nwz i niuqtg wn nwcz. - - -
- - -
- -
- - \ No newline at end of file diff --git a/src/ciphers/ciphers.md b/src/ciphers/ciphers.md deleted file mode 100644 index 14e0c97..0000000 --- a/src/ciphers/ciphers.md +++ /dev/null @@ -1,5 +0,0 @@ -# 🐸 CIPHERS 🐸 - -> [!INFO] Encryption & Decryption -> Welcome to the world of encrypting and decrypting ciphers! -> Slides can be found with this link diff --git a/src/ciphers/rot13.md b/src/ciphers/rot13.md deleted file mode 100644 index d1ccbab..0000000 --- a/src/ciphers/rot13.md +++ /dev/null @@ -1,63 +0,0 @@ -# 🔑 ROT13 CIPHER 🔑 -The ROT13 cipher is a substitution cipher where each letter is replaced by the letter 13 places down the alphabet. It is a special case of the Caesar cipher with a shift of 13. - -## How It Works -- Replace each letter with the letter 13 positions down the alphabet. -- Wrap around to the beginning of the alphabet if necessary. -- Applying ROT13 twice returns the original text. -- USE YOUR CIPHER WHEEL! - -## Decrypting ROT13 Ciphers -> [!SUCCESS] Task -> Decrypt the following ciphers. Note that **punctuation matters** when inputting your answers. Upper and lower case does not matter. -> -> The following all use the ROT13 cipher. - -### Cipher 1 -Qvq lbh xabj... Cvenpl jnf na rkgerzryl pbzcrgvgvir ohfvarff. Cvengrf jbhyq bsgra wbva sbeprf jvgu bar nabgure, sbezvat nyyvnaprf naq syrrgf, va beqre gb vapernfr gurve punaprf bs fhpprff naq znkvzvfr gurve cebsvgf. - - -
- - -
- -
- -### Cipher 2 -Va gur pnaqyryvg unyyf bs Ubtjnegf, frpergf geniry snfgre guna bjyf, naq rirel juvfcre pneevrf gur jrvtug bs zntvp naq zvfpuvrs. - - -
- - -
- -
- - \ No newline at end of file diff --git a/src/ciphers/rsa.md b/src/ciphers/rsa.md deleted file mode 100644 index 34a2620..0000000 --- a/src/ciphers/rsa.md +++ /dev/null @@ -1,95 +0,0 @@ -# ASYMMETRIC ENCRYPTION & RSA - -## What Makes It *Asymmetric*? - -- In **symmetric encryption**, the **same key** is used to both encrypt and decrypt. - - For instance, in the Ceaser Ciphers covered earlier, we use the same key to encrypt (shift forwards) and decrypt (shift backwards). -- In **asymmetric encryption**, there are **two different keys**: - - **Public key**: used to lock (encrypt) the message 🔓 - - **Private key**: used to unlock (decrypt) the message 🔑 - -We call it *asymmetric* since the keys are not the same for encrypting and decrypting. - -This means you can safely share your public key with the world, -while keeping your private key secret. - - -## Why Do We Need RSA? -- Symmetric ciphers (like Substitution or Caesar) need both people to share the same secret key. -- But how do we share that key securely over the internet? -- This is a big problem for symmetric encryption schemes. -- RSA solves this by letting you publish your public key so anyone can encrypt messages to you. -- Only your secret private key can decrypt it. - ---- - -## How Does RSA Work? (Simplified) -1. Pick two prime numbers (For this example we will use 5 and 11) -2. Multiply them together (n = 5 × 11 = 55). -3. Choose a **public exponent** (we will choose e = 3). -4. Work out a **private exponent** (this is quite difficult to do but in this case, d = 27 will work). -5. We will chose 9, as our message. -6. To encrypt: Raise message to the public exponent, then mod by 55. c = (9^3 mod 55) = 14 -7. To decrypt: Raise ciphertext to the private exponent, mod by 55. m = (14^27 mod 55) = 9 which was our message! - ---- - -## Practice Task - -### Task 1: Encryption -Bob’s RSA public key, n = 55 and public exponent, e = 3. -Alice wants to send him the message, m = 4. -What is the ciphertext? (encrypted message) - -**Try to solve before opening the answer!** - -
- Show Answer - - **Step 1:** formula - `ciphertext = message^e mod n` - - **Step 2:** plug in numbers - `ciphertext = 4^3 mod 55` - - **Step 3:** calculate the power - `4^3 = 64` - - **Step 4:** calculate 64 mod 55 - `64 mod 55 = 9` - - **Ciphertext = 9** - -
- ---- - -### Task 2: Decryption -Bob’s private key, d = 27 and public exponent, n = 55. -He receives ciphertext, c = 9. -What is the hidden message, m? -Hint (use this calculator for large values: https://www.wolframalpha.com) - -**Try to solve before opening the answer!** - -
- Show Answer - - **Step 1:** formula - `message = ciphertext^d mod n` - - **Step 2:** plug in numbers - `message = 9^27 mod 55` - - **Step 3:** calculate the power (we will need a powerful online calculator like wolfram alpha: - https://www.wolframalpha.com/input?i=9%5E27) - `9^27 = 58149737003040059690390169` - - **Step 4:** calculate 58149737003040059690390169 mod 55 (we will also use wolframalpha: - https://www.wolframalpha.com/input?i=58149737003040059690390169+mod+55) - - `58149737003040059690390169 mod 55 = 4` - - **Decrypted message = 4** - -
diff --git a/src/examples/answer-widget.md b/src/examples/answer-widget.md new file mode 100644 index 0000000..044a53f --- /dev/null +++ b/src/examples/answer-widget.md @@ -0,0 +1,53 @@ +# Answer widgets + +Use an answer widget when you want readers to type a response and check it inline — useful for short exercises or puzzles. + +> [!NOTE] Copy-paste pattern +> This is a simple HTML + inline script pattern for now. A shared preprocessor or plugin may replace per-page scripts in a future update. + +## Example + +**Question:** Which organisation maintains this handbook template? + +
+ + +
+ +
+ + + +## How to add your own + +1. **Choose the correct answer** and encode it as Base64 (e.g. in a terminal: `echo -n 'your answer' | base64`). +2. **Copy the HTML** from the example above into your `.md` file. +3. **Use unique ids** for each widget on the page (`answerinput1`, `result1`, etc.) so multiple boxes do not clash. +4. **Include the ` + {{/if}} + + + + + + + +
+
+

Keyboard shortcuts

+
+

Press ← or → to navigate between chapters

+ {{#if search_enabled}} +

Press S or / to search in the book

+ {{/if}} +

Press ? to show this help

+

Press Esc to hide this help

+
+
+
+
+ + + + + + + + + + + + + +
+ +
+ {{> header}} +
+ + + {{#if search_enabled}} + + {{/if}} + + + + +
+
+ {{{ content }}} +
+ + +
+
+ + + +
+ + + + + + + + {{#if live_reload_endpoint}} + + + {{/if}} + + {{#if playground_line_numbers}} + + {{/if}} + + {{#if playground_copyable}} + + {{/if}} + + {{#if playground_js}} + + + + + + {{/if}} + + {{#if search_js}} + + + + {{/if}} + + + + + + + {{#each additional_js}} + + {{/each}} + + {{#if is_print}} + {{#if mathjax_support}} + + {{else}} + + {{/if}} + {{/if}} + + {{#if fragment_map}} + + {{/if}} + +
+ + From 6dd6dc18de60f99389b36ec0ae856bba371016be Mon Sep 17 00:00:00 2001 From: Bassem Kidwai Date: Thu, 25 Jun 2026 14:30:20 +1000 Subject: [PATCH 04/24] bassem/ticket-3: add workshop-specific theme --- theme/css/variables.css | 63 +++++++++++++++++++++++++++++++++++++++++ theme/index.hbs | 1 + 2 files changed, 64 insertions(+) diff --git a/theme/css/variables.css b/theme/css/variables.css index af5023b..235d6ac 100644 --- a/theme/css/variables.css +++ b/theme/css/variables.css @@ -16,6 +16,69 @@ /* Themes */ +/* Custom Theme for your Workshop! */ + +.workshop { + --bg: hsl(210, 25%, 8%); + --fg: #c5c5c5; + + --sidebar-bg: #14191f; + --sidebar-fg: #c8c9db; + --sidebar-non-existant: #5c6773; + --sidebar-active: #ffb454; + --sidebar-spacer: #2d334f; + + --scrollbar: var(--sidebar-fg); + + --icons: #737480; + --icons-hover: #b7b9cc; + + --links: #0096cf; + + --inline-code-color: #ffb454; + + --theme-popup-bg: #14191f; + --theme-popup-border: #5c6773; + --theme-hover: #191f26; + + --quote-bg: hsl(226, 15%, 17%); + --quote-border: hsl(226, 15%, 22%); + + --warning-border: #ff8e00; + + --table-border-color: hsl(210, 25%, 13%); + --table-header-bg: hsl(210, 25%, 28%); + --table-alternate-bg: hsl(210, 25%, 11%); + + --searchbar-border-color: #848484; + --searchbar-bg: #424242; + --searchbar-fg: #fff; + --searchbar-shadow-color: #d4c89f; + --searchresults-header-fg: #666; + --searchresults-border-color: #888; + --searchresults-li-bg: #252932; + --search-mark-bg: #e3b171; + + --color-scheme: dark; + + /* Same as `--icons` */ + --copy-button-filter: invert(45%) sepia(6%) saturate(621%) hue-rotate(198deg) brightness(99%) contrast(85%); + /* Same as `--sidebar-active` */ + --copy-button-filter-hover: invert(68%) sepia(55%) saturate(531%) hue-rotate(341deg) brightness(104%) contrast(101%); + + --footnote-highlight: #2668a6; + + --overlay-bg: rgba(33, 40, 48, 0.4); + + --blockquote-note-color: #74b9ff; + --blockquote-tip-color: #09ca09; + --blockquote-important-color: #d3abff; + --blockquote-warning-color: #f0b72f; + --blockquote-caution-color: #f21424; + + --sidebar-header-border-color: #c18639; +} + .ayu { --bg: hsl(210, 25%, 8%); --fg: #c5c5c5; diff --git a/theme/index.hbs b/theme/index.hbs index b183418..b5c1f84 100644 --- a/theme/index.hbs +++ b/theme/index.hbs @@ -156,6 +156,7 @@
    • +
    • {{#if search_enabled}} --}} +``` diff --git a/theme/index.hbs b/theme/index.hbs index b5c1f84..4b1b534 100644 --- a/theme/index.hbs +++ b/theme/index.hbs @@ -156,7 +156,8 @@
    • -
    • + {{!-- Enable your custom theme here! --}} + {{!--
    • --}} {{#if search_enabled}} --}} ``` + +## Poco Cursor +By default, we have a Poco cursor enabled in the template. If you want to remove it, head over to `theme/variables.css` and set the below variables to `auto`: +```css +--plain-poco-cursor: url("../assets/plain-poco-xs.png"), auto; +--active-poco-cursor: url("../assets/active-poco-xs.png"), auto; +``` \ No newline at end of file diff --git a/theme/css/chrome.css b/theme/css/chrome.css index 232a8c2..8149bfb 100644 --- a/theme/css/chrome.css +++ b/theme/css/chrome.css @@ -61,7 +61,7 @@ html.sidebar-visible #mdbook-menu-bar { padding: 0 8px; z-index: 10; line-height: var(--menu-bar-height); - cursor: pointer; + cursor: var(--active-poco-cursor); transition: color 0.5s; } @media only screen and (max-width: 420px) { @@ -108,7 +108,7 @@ html:not(.js) .left-buttons button { text-overflow: ellipsis; } .menu-title { - cursor: pointer; + cursor: var(--active-poco-cursor); } .menu-bar, @@ -120,6 +120,7 @@ html:not(.js) .left-buttons button { .menu-bar .icon-button, .menu-bar a .fa-svg { color: var(--icons); + cursor: var(--active-poco-cursor); } .menu-bar .fa-svg:hover, @@ -212,6 +213,11 @@ html:not(.js) .left-buttons button { a:hover > .hljs { text-decoration: underline; + cursor: var(--active-poco-cursor); +} + +a:hover { + cursor: var(--active-poco-cursor); } pre { @@ -226,7 +232,7 @@ pre > .buttons { padding: 2px 0px; color: var(--sidebar-fg); - cursor: pointer; + cursor: var(--active-poco-cursor); visibility: hidden; opacity: 0; transition: visibility 0.1s linear, opacity 0.1s linear; @@ -241,7 +247,7 @@ pre > .buttons :hover { background-color: var(--theme-hover); } pre > .buttons button { - cursor: inherit; + cursor: var(--active-poco-cursor); margin: 0px 5px; padding: 2px 3px 0px 4px; font-size: 23px; @@ -323,7 +329,7 @@ mark { margin-inline-end: -3px; background-color: var(--search-mark-bg); transition: background-color 300ms linear; - cursor: pointer; + cursor: var(--active-poco-cursor); } mark.fade-out { @@ -705,7 +711,7 @@ html:not(.js) .sidebar-resize-handle { line-height: 25px; white-space: nowrap; text-align: start; - cursor: pointer; + cursor: var(--active-poco-cursor); color: inherit; background: inherit; font-size: inherit; diff --git a/theme/css/general.css b/theme/css/general.css index 91401e3..0ee9d81 100644 --- a/theme/css/general.css +++ b/theme/css/general.css @@ -18,6 +18,7 @@ body { margin: 0; font-size: 1.6rem; overflow-x: hidden; + cursor: var(--plain-poco-cursor); } code { diff --git a/theme/css/print.css b/theme/css/print.css index 2004384..90056d9 100644 --- a/theme/css/print.css +++ b/theme/css/print.css @@ -33,6 +33,7 @@ pre > .buttons { a, a:visited, a:active, a:hover { color: #4183c4; text-decoration: none; + cursor: var(--active-poco-cursor); } h1, h2, h3, h4, h5, h6 { diff --git a/theme/css/variables.css b/theme/css/variables.css index ed84e38..d669849 100644 --- a/theme/css/variables.css +++ b/theme/css/variables.css @@ -12,6 +12,10 @@ --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; --code-font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ --searchbar-margin-block-start: 5px; + + /* set the below variables to auto if you don't want the Poco cursor */ + --plain-poco-cursor: url("../assets/plain-poco-xs.png"), auto; + --active-poco-cursor: url("../assets/active-poco-xs.png"), auto; } /* Themes */ From 373754225746d5543eb17729d3d2b057f178c83d Mon Sep 17 00:00:00 2001 From: Bassem Kidwai Date: Sat, 27 Jun 2026 15:01:54 +1000 Subject: [PATCH 16/24] feet/ticket-3: add docs for font changes --- TODO.md | 6 ------ theme/THEME.md | 10 +++++++--- theme/css/general.css | 2 +- theme/css/variables.css | 11 +++++++++++ theme/index.hbs | 2 +- 5 files changed, 20 insertions(+), 11 deletions(-) delete mode 100644 TODO.md diff --git a/TODO.md b/TODO.md deleted file mode 100644 index de8e267..0000000 --- a/TODO.md +++ /dev/null @@ -1,6 +0,0 @@ -# Braindump - -I'll put my braindump here, will remove before merging. - -Re-add Poco cursor (the goat), and instructions to remove it -Add comments to CSS (seems self explanatory, check w dictators if ts is needed) \ No newline at end of file diff --git a/theme/THEME.md b/theme/THEME.md index 6e559dc..63f8db3 100644 --- a/theme/THEME.md +++ b/theme/THEME.md @@ -5,15 +5,19 @@ At the moment, the repo is loaded with the themes provided by mdbook, with the d If you wish to change to another one of the default themes, feel free to make that change in `book.toml`. All the themes should be in `theme/css/variables.css`. That leads us onto the next part... ## Creating your own custom theme! -In `theme/css/variables.css`, there's an extra theme called `.workshop`. Feel free to experiment and play around with the colours in this block. If you choose to use this for your workshop, update the `default_theme` entry in `book.toml`, and replace the name with whatever you want in `theme/index.hbs`. Also uncomment the below code block: +In `theme/css/variables.css`, there's an extra theme called `.workshop`. Feel free to experiment and play around with the colours in this block. If you choose to use this for your workshop, update the `default_theme` entry in `book.toml`, and replace the name with whatever you want in `theme/index.hbs`. If you choose to not have a custom theme, then comment the below code block: ```css {{!-- Enable your custom theme here! --}} -{{!--
    • --}} +
    • ``` +### Fonts +Your fonts can also be customised in `theme/css/variables.css`. You can set a font that applies to all themes within the `:root` object. By default its set to the standard mdbook font-family. Alternatively, if you just want a custom font for your workshop, then you can adjust the font variables in the `.workshop` object. + + ## Poco Cursor By default, we have a Poco cursor enabled in the template. If you want to remove it, head over to `theme/variables.css` and set the below variables to `auto`: ```css --plain-poco-cursor: url("../assets/plain-poco-xs.png"), auto; --active-poco-cursor: url("../assets/active-poco-xs.png"), auto; -``` \ No newline at end of file +``` diff --git a/theme/css/general.css b/theme/css/general.css index 0ee9d81..a8489ce 100644 --- a/theme/css/general.css +++ b/theme/css/general.css @@ -7,7 +7,7 @@ } html { - font-family: "Open Sans", sans-serif; + font-family: var(--custom-font-family), "Open Sans", sans-serif; color: var(--fg); background-color: var(--bg); text-size-adjust: none; diff --git a/theme/css/variables.css b/theme/css/variables.css index d669849..8a3acc3 100644 --- a/theme/css/variables.css +++ b/theme/css/variables.css @@ -9,7 +9,12 @@ --page-padding: 15px; --content-max-width: 750px; --menu-bar-height: 50px; + /* Pick a custom font fmily for the entire page here */ + /* Defaults the standard mdbook font family */ + --custom-font-family: "Open Sans", sans-serif; + /* Pick the font used in code blocks here */ --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + --code-font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ --searchbar-margin-block-start: 5px; @@ -23,6 +28,12 @@ /* Custom Theme for your Workshop! */ .workshop { + /* These fonts will only be active when the workshop theme is enabled */ + /* Set a custom font-family for your workshop here! */ + --custom-font-family: "Papyrus"; + /* Pick a custom monospace font for your code blocks here !*/ + --mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace; + --bg: hsl(210, 25%, 8%); --fg: #c5c5c5; diff --git a/theme/index.hbs b/theme/index.hbs index 4b1b534..9b8ddc8 100644 --- a/theme/index.hbs +++ b/theme/index.hbs @@ -157,7 +157,7 @@
    • {{!-- Enable your custom theme here! --}} - {{!--
    • --}} +
    • {{#if search_enabled}}