swe-site

MkDocs Material site that publishes four sections as one site at https://swe.springlee.dev, deployed on Cloudflare Pages.

Layout

Content sources live under content/:

Section	Source	Tracked how
LeetCode Algorithms	content/leetcode-algorithms/	git submodule → leetcode-algorithms
SWE Interview	content/swe/	in this repo
System Design	content/system-design/	in this repo (vendored from liquidslr/system-design-notes)
Real Interview Questions	content/real-interview-questions/	in this repo

Three of the four sections are edited here directly. Only LeetCode stays a separate repo, because it has its own GitBook publication, PR workflow and solution-generation tooling.

How it works

• scripts/prepare.sh copies content/* into docs/leetcode/, docs/swe/, docs/system-design/ and docs/real-interview-questions/, relocates GitBook assets to _assets/, and converts each source's GitBook SUMMARY.md into mkdocs-literate-nav format via scripts/convert_summary.py.
• docs/SUMMARY.md defines the top-level tabs (Home / LeetCode Algorithms / SWE Interview / System Design / Real Interview Questions); each section's nav comes from its converted SUMMARY.
• swe and real-interview-questions are copied the same way — every *.md except SUMMARY.md and their own CLAUDE.md — so maintenance docs stay out of the published site.
• system-design has no SUMMARY.md, so scripts/gen_nav.py generates one from its NN. Chapter Name/README.md folders, ordered by the numeric prefix and labelled with each chapter's H1. It also mixes Readme.md and README.md casing; prepare.sh normalises it, because only an exact README.md becomes a directory index and the chapters' raw <img src="./images/..."> tags resolve only from that index URL.
• Math: content uses GitBook-style inline $$O(...)$$; rendered client-side by KaTeX auto-render (docs/javascripts/katex.js).

Local development

git clone --recurse-submodules https://github.com/software-engineer-learning/swe-site.git
# already cloned without it:
git submodule update --init --recursive

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
bash scripts/prepare.sh
.venv/bin/mkdocs serve   # http://127.0.0.1:8000

Edit content/swe/, content/system-design/ and content/real-interview-questions/ in place, then re-run prepare.sh. Never edit under docs/ — prepare.sh wipes those four directories on every run.

To pull new LeetCode solutions into your checkout:

git submodule update --remote content/leetcode-algorithms

The submodule pointer committed here is intentionally allowed to go stale — CI always builds the submodule's latest main (see below), so bumping the pointer is optional housekeeping rather than a release step.

CI/CD

Deploys are done by GitHub Actions (.github/workflows/deploy.yml), not by Cloudflare's Git integration — do not also connect the repo in the Cloudflare dashboard or every change would build twice. The workflow checks out submodules, runs git submodule update --remote on the LeetCode submodule so the newest solutions are published, builds the site, and uploads it with wrangler pages deploy. It runs on:

• pushes to main of this repo — which now covers every edit to the SWE, System Design and Real Interview Questions sections,
• repository_dispatch events of type content-updated, fired by leetcode-algorithms' gitbook.yml workflow on its content pushes,
• manual runs (workflow_dispatch).

Updating the vendored system-design notes

content/system-design/ is a vendored copy of our fork of the third-party liquidslr/system-design-notes. Because it is vendored rather than cloned at build time, syncing the fork no longer reaches the site on its own — pull upstream changes in by hand:

gh repo sync software-engineer-learning/system-design-notes --source liquidslr/system-design-notes
git clone --depth 1 https://github.com/software-engineer-learning/system-design-notes.git /tmp/sd
rsync -a --delete --exclude '.git/' --exclude '.github/' /tmp/sd/ content/system-design/
bash scripts/prepare.sh && .venv/bin/mkdocs build --strict

Review the diff before committing — vendoring is what keeps third-party edits from landing on the site unreviewed.

One-time setup

1. Create the Pages project (Direct Upload):

   npx wrangler pages project create swe-site --production-branch=main

   (or Cloudflare dashboard → Workers & Pages → Create → Pages → Direct Upload.)

2. In this repo's GitHub settings → Secrets and variables → Actions, add:

   • CLOUDFLARE_ACCOUNT_ID — dashboard → Workers & Pages → right sidebar.
   • CLOUDFLARE_API_TOKEN — dashboard → My Profile → API Tokens → Create Token → "Edit Cloudflare Workers"-style custom token with Account → Cloudflare Pages → Edit permission.

3. SITE_DISPATCH_TOKEN — a classic PAT with the repo scope on an account that can write to software-engineer-learning/swe-site, held as an organization-level secret. Only leetcode-algorithms still needs it, since it is the one content repo left outside this one. Write access is what authorizes repository_dispatch.

   Don't use a Cloudflare Pages deploy hook here. This project is Direct Upload, so a hook has no repo to clone and no build command to run — it re-serves the assets already uploaded and returns success: true while the content stays stale. Deploy hooks only build on Git-connected Pages projects, and connecting this repo would make every change build twice.

4. After the first deploy: Pages project → Custom domains → Add → swe.springlee.dev. With the springlee.dev zone on Cloudflare, the CNAME and TLS are automatic.

Adding a section

1. Put the markdown under content/<section>/ (or add a submodule there).
2. In scripts/prepare.sh: add a <x>_src variable, an entry in the existence check, the rm -rf/mkdir -p entries, a copy block, a convert_summary.py call writing docs/<section>/SUMMARY.md, and the dir in the final page-count find and the normalize_fences.py call.
3. Add the tab to docs/SUMMARY.md and a bullet to docs/index.md.
4. Add the section to the table above.