A small, dependency-free reading interface for the learn-* course
collection. It turns the Markdown in each course repository into a book-like
website: a home page of course cards, a per-course sidebar of chapters, and
clean, syntax-highlighted pages.
Live site (once Pages is enabled): https://sipak-gh.github.io/courseware/
There is no build step and no server code. The site is a single HTML page plus a little CSS and JavaScript:
manifest.jsonlists every course and the ordered Markdown files in it (titles only — used to build navigation).- At view time, the page body is fetched live from
raw.githubusercontent.com/<org>/<repo>/<branch>/<file>and rendered in the browser with marked and highlight.js (both from a pinned CDN).
Because content is fetched live, the site always reflects whatever is on each
repository's master branch — just push a course and its pages update. No
submodules, no copies.
Note: a course's pages only render once that course is pushed to GitHub. A freshly created but unpushed course will show a "couldn't load" message until you push it.
- Markdown pages (
README.md,NN-*.md,appendix-*.md,REFERENCES.md) are rendered as book pages. Code snippets (fenced and inline) are shown inline and syntax-highlighted. - Links to any non-Markdown file (source code, assets) point back to that
file on GitHub rather than being rendered here — so
examples/sol.pyopens on GitHub, while02-next.mdnavigates within the reader. - Because rendering happens in the browser, course content is shown verbatim;
there is no server-side templating to misread code such as
DUCTF{%s}.
#/ home (course cards)
#/<repo> course home (renders README.md)
#/<repo>/<file.md> a specific page
#/<repo>/<file.md>::slug a page scrolled to a heading
gen_manifest.py scans the sibling learn-* repositories checked out next to
this one (e.g. ~/learn-c, ~/learn-go, …). Re-run it after adding, renaming,
or reordering chapters:
python3 gen_manifest.pyIt reads each course's README.md for a title and summary, orders the content
files (README.md → NN-*.md → appendix-*.md → REFERENCES.md), and writes
manifest.json. Topics (their order, titles and blurbs, and which courses each
holds, in order) live in the TOPICS table near the top of the script; the
home page and course switcher are grouped by them. Per-course display metadata
(language label, accent colour) lives in META. A new learn-* repo that is
not listed in TOPICS still appears, under "Other".
By default it scans the parent directory for sibling learn-* clones; pass an
explicit directory to scan elsewhere:
python3 gen_manifest.py /path/to/clones.github/workflows/update-manifest.yml keeps manifest.json current without
any local work. It runs every Monday 07:00 UTC and on demand (Actions →
Update manifest → Run workflow). Each run shallow-clones the public learn-*
repos, regenerates the manifest, and commits it only if it changed.
Scheduled Actions are free and unlimited on public repos, and this job is tiny. One setup requirement: under Settings → Actions → General → Workflow permissions, select Read and write permissions so the workflow can push the updated manifest.
- Create the
coursewarerepository under thesipak-ghorg and push this folder to themasterbranch. - In Settings → Pages, set Source to Deploy from a branch, branch
master, folder/ (root). - Visit
https://sipak-gh.github.io/courseware/.
(The .nojekyll file tells Pages to serve the files as-is rather than running
them through Jekyll.)
python3 -m http.server 8000
# open http://localhost:8000/Serving over HTTP (not file://) is required so fetch can load
manifest.json and the live Markdown.