Convert to MySTMD#315
Conversation
❌ Deploy Preview for learn-scientific-python-org failed.Built without sensitive environment variables
|
|
I've put together a plan for the migration, including REQUIREMENTS.md, and Architectural Decision Records (ADRs), which need review, and a detailed PLAN.md document. Recommended Review order:
Ai Tools Disclaimer: |
lundybernard
force-pushed
the
lb/myst-migration
branch
2 times, most recently
from
0f29f3f to
4f6f3c4
Compare
|
From what I see, the plan looks fine. While I was excited about the Jekyll -> Hugo migration (fast, secure single binary, static easily themeable HTML), I'm not quite as excited about mystmd transition (Frankenstein of nodejs+Python, JS-powered pages). I get several source map loading errors when opening https://mystmd.org/guide. But I do really like it for course material, and some of our material basically is that. I'd probably not worry about trying to replicate the theme at all at first (which I think matches the decisions made, like the deferred footer). I'm curious if you've done the basic conversation table for the other subrepos? I'm curious to see what it says about the special stuff in cookie, like our tabs. I know exactly how to do that in Hugo (I maintain a Hugo theme ;) ), I'm curious to know how those would map to mystmd. I'm very slightly tempted to do Jekyll -> Hugo with cookie, and then look at Hugo -> mystmd. But yes, plan looks good. What do you feed into the next step, just the PLAN.md? |
|
I've only done a cursory look at converting the other sub-repos, a quick "is it possible, any major blockers?" check. Now's probably a good time to build a report and add it to the parent ticket. I take a very hand-on approach with Ai tools, so I wont feed a big "one-shot" prompt into an agent and lets it run for hours. I've been using claude code, with broad read-only permissions, and it pulls in a lot of context about the repo when I start it up. So, the input is a heuristic search of the learn repository, and access to external docs as-needed. |
Adds the full planning record for the Hugo → MyST-MD migration to docs/decisions/0001-myst-migration/: - REQUIREMENTS.md — what the migration must achieve and why - PLAN.md — commit-by-commit 8-phase implementation sequence - 0001–0007 ADR files — one decision per file, all Status: Proposed - README.md — index of the above ADR format is used so the decision rationale survives as a reviewable archive. All ADRs are Proposed pending maintainer review; the plan and requirements are the working basis for the migration work to follow.
lundybernard
force-pushed
the
lb/myst-migration
branch
2 times, most recently
from
a85c0ad to
03f979b
Compare
|
For generic landing pages, we've started working on https://github.com/scientific-python/scientific-python-myst-theme/ (early stages of a cookie cutter). Agreed that porting content first is a good idea: we can tweak the theme later. myst is not supposed to be a "Frankenstein of nodejs+Python, JS-powered pages" — it is a typescript application (runtime Node or Bun). But, I get the concern about the complexity, and of course the source map errors should be addressed. Hugo's big strength is in how easily extendible it is, without needing to tinker with the code, whereas myst themes are all full-fledged web servers & logic. |
|
Surfaced a bug: Confirmed on the live site, these are dead-links on https://learn.scientific-python.org/contributors/getting-started/ |
- myst.yml: new; project.id, inline toc for content/ tree, excludes submodules - fixed project.id UUID, exclude submodule dirs (external-content/, themes/) - .gitignore: add _build/ the MyST output directory - ADR 0001: Accepted
_index.md is a Hugo idiom; MyST excludes _-prefixed files from auto-discovery. Renames done before content changes so all later commits reference the final filenames.
Mapping (per ADR 0002):
{{< admonition warning >}}…{{< /admonition >}} → :::{warning}…:::
{{< admonition note >}}…{{< /admonition >}} → :::{note}…:::
shortcutDepth was a Hugo theme option controlling sidebar depth. MyST has no equivalent and warns on unknown frontmatter keys.
Hugo silently rendered [text]() as href=""; MyST raises build errors. Added URLs for astropy, sunpy, numpy, scipy, matplotlib, and a Wikipedia link for "integrated development environment".
- html: hugo → myst build --html (output now in _build/html/) - html-all: copy _build/html/ to public/ then build external content - serve: hugo server → myst start - clean: also removes _build/
lundybernard
force-pushed
the
lb/myst-migration
branch
from
fa11914 to
cda6104
Compare
Remove Hugo/Dart Sass toolchain (HUGO_VERSION, DART_SASS_VERSION, DART_SASS_URL env vars and the curl/tar/PATH install block). MyST ships pre-built CSS; no Sass compilation step required. Add `pip install mystmd` before `make html-all`. Keep PYTHON_VERSION, publish = "public", and netlify-plugin-checklinks unchanged.
Port description, nav, domain, and logo from config.yaml. Rename static/ → assets/ (Hugo directory convention; MyST does not serve static/ automatically — assets/ is the expected path). No dark logo or favicon: neither existed in the Hugo static/ dir; MyST supplies a default favicon. Footer/quicklinks deferred per ADR 0005.
- Delete config.yaml (metadata ported to myst.yml in previous commit) - Remove scientific-python-hugo-theme submodule (only consumed by Hugo; other SP repos vendor their own copy — ADR 0003) - Drop .hugo* and resources/ from .gitignore; both are Hugo-specific. _build/ was already present; public/ kept for html-all output.
Netlify's link checker is failing due to a URL structure mismatch between Hugo and MyST.
lundybernard
force-pushed
the
lb/myst-migration
branch
from
762d801 to
9597dec
Compare
3 participants
Migrate from Hugo to MyST-MD
Fixes: #279