kangwonlee / kangwonlee/nmisp

Docs: surface per-chapter link-page.md Colab indexes from the README (+ a generator to keep them fresh)

Open
#446 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Jupyter Notebook
Stars
12
Forks
76
PR merge metrics
No merged PRs in 30d

Description

## Context

Every chapter folder now has a `link-page.md` Colab index — a bilingual table of one-click Colab badges generated from the git-tracked notebooks. Coverage: `40_linear_algebra_1` / `60_linear_algebra_2` (earlier) plus `00_introduction`, `10_root_finding`, `15_optimization`, `20_probability`, `28_interpolation`, `30_num_int`, `35_sympy`, `50_ode`, `tutorial` (added 2026-06-01, commit `d3c2ea79`).

But nothing points to them. The README's folder table lists topics, not the indexes, so a visitor has to already know the files exist. (Left standalone for now per the 2026-06-01 decision.)

## Proposed (deferred)

1. **Surface the link-pages from the README** — e.g. make each folder name in the README chapter table link to its `link-page.md`, or add a short "per-chapter Colab index" line. A draft of this was tried earlier and reverted pending a decision.
2. Optionally, a single top-level index page (or README section) listing all chapters' link-pages.

## Maintenance note (worth pairing with the above)

The link-pages are currently **hand-generated** (glob git-tracked notebooks → first H1 as title → Colab badge table). They will **go stale on renumber / add / remove**. Promoting the inline generator used for the 2026-06-01 batch into a committed `utils/gen_link_pages.py` — runnable in pre-commit or CI — would keep them in sync. Notes for that script:
- Use **git-tracked** notebooks only (the batch initially swept in untracked scratch like `ODE examples *` / `eca wk06 sample`; exclude those).
- Title from the notebook's first H1, `
` → ` / `.
- `link-page.md` is the ONE place hard file links are acceptable (regenerated from actual files), so it does not conflict with the concept-name cross-reference rule used elsewhere.

Parked from the 2026-06-01 session.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.