A beginner-friendly, static website that teaches new HKU postgraduate students how to install a Python environment and run their first lessons. Content is written in Markdown and rendered to HTML in the browser — no build step required.
- Each HTML page is a thin shell. Its
<body>carriesdata-md="<file>.md". assets/js/render.jsfetches that Markdown file, parses it withmarkedand sanitizes it withDOMPurify, then injects the HTML into the page.- The top navigation, the index chapter cards, the sidebar table of contents, the
Required/Optional/Skippable tag, and the Prev/Next pager are all generated automatically
from
assets/js/site.jsand from each.mdfile's frontmatter. - TDesign web components are loaded via CDN
and used for the chapter tag chips (
<t-tag>). If the CDN is blocked, the page falls back to plain CSS — it still works. (shadcn requires React + a bundler, so it is not used in this no-build static site.)
- Open the relevant
.mdfile (index.mdorpages/<chapter>.md). - Edit the text. Frontmatter at the top controls the page title and tag:
--- title: 3 · Installing Python tag: Required ---
- Save and refresh the browser — the HTML updates instantly. No compilation.
- Standard Markdown: headings, lists, tables, fenced code blocks, links, images.
- Emoji callouts become callouts: start a blockquote with
> 📝(note),> 💡(tip),> ⚠️(warning), or> ❗(important). Do not use GitHub-style alert syntax (> [!NOTE]etc.), which only renders on GitHub. - A standalone image
is wrapped in a<figure>with thealttext as the caption. Useassets/img/placeholder.svgas a placeholder and replacesrclater. - Shell code blocks (
bash/sh/zsh/powershell/cmd) get colored$prompts and#comments automatically. - Use
<!-- TODO: ... -->comments in the Markdown for authoring notes (they are hidden when rendered).
- Create
pages/<name>.mdwithtitle/tagfrontmatter. - Create
pages/<name>.htmlcopying any existing shell and settingdata-md="<name>.md". - Add an entry to
window.SITE.chaptersinassets/js/site.js({ name, n, title, tag, desc }). The nav, index cards, and pager update automatically.
The site is markdown-driven: each page fetch()es its .md and renders it in the
browser, so content is never compiled — it is read live. To see your edits, the browser
just needs to reload the .md.
serve.py is a zero-dependency live-reload server. It watches every .md/.html/.css/
.js file and tells the browser to reload the moment you save:
python3 serve.py 8000
# edit any .md, save, and the page reloads automaticallyNo pip install, no bundler. The HTML served is still plain static files, so GitHub
Pages deployment is unchanged. (If you prefer Node tooling, npx browser-sync start --server --files "**/*" does the same thing.)
You can use any static server; just refresh the browser after saving:
python3 -m http.server 8000
# then visit http://localhost:8000/ and refresh after editsWhy not open the
.htmldirectly? The browser blocksfetch()of local files overfile://. Always serve over HTTP (either option above).
The site is plain static files — push to the repo and enable GitHub Pages on the branch
(root). No Jekyll or build step is needed. marked, DOMPurify, and TDesign are loaded
from jsDelivr, so the live site needs internet access for those scripts.
See AGENTS.md for the full plan. Chapters are skeletons with placeholder text and TODO
markers; the structure, navigation, and Markdown rendering pipeline are complete.