What Learn is
/learn is a knowledge base about getting started in open source, published on the site as
26 chapters across two tracks:
Chapters are plain MDX files at the repository root, not inside
src/. Contributing one
needs no TypeScript and no React. If you can write Markdown, you can contribute here.
Read the tracks
See what’s already published before writing something new.
Editing an existing chapter
Find the file by its slug and edit it. The URL/learn/getting-started maps to
content/learn/getting-started.mdx.
Adding a new chapter
1
Create the MDX file
Add it to
content/learn/ or content/hands-on/, named after its slug:2
Write the frontmatter
Two fields, both quoted:
3
Register it in the index
A file on disk is not enough. The chapter must be listed in
content/chapters.ts, in
learnChapters or handsOnChapters:order drives both the listing order and the previous/next navigation at the bottom of
each chapter. description is optional here. The page reads it from the MDX frontmatter.4
Check it renders
/learn, /learn/chapters, and your chapter’s own URL.What you can use in a chapter
Content is rendered withreact-markdown plus GitHub Flavored Markdown and raw HTML support,
with syntax highlighting for code blocks. In practice: headings, lists, tables, links, images,
blockquotes, inline and fenced code all work.
Headings become entries in the table of contents shown beside the chapter, so structure your
chapter with ## and ### rather than bold paragraphs.
Despite the
.mdx extension, chapters are parsed as Markdown with hand-read frontmatter.
they are not compiled MDX modules. Don’t add import statements or JSX components; they
won’t execute.Before you open the pull request
pnpm build matters here: chapters are prerendered at build time, so this is where a broken
chapter shows up.
One thing the build will not catch: it only reads content/chapters.ts, never the folders.
An .mdx file you forgot to register is silently unreachable, and a registry entry with no file
just renders empty. Check your chapter’s URL yourself before opening the PR.
For deployment,
pnpm worker:build runs scripts/copy-learn-html.js, which copies the
prerendered chapter HTML into the Cloudflare Workers asset bundle. You don’t need to run it
locally, but it’s why the build step can’t be skipped.Style
- Write for someone making their first contribution, not for a maintainer.
- Prefer concrete examples over abstract advice.
- Keep chapters roughly the length of the existing ones (3–5 KB of prose).
- Link to real projects and real documentation rather than paraphrasing them.
Back to contributing
Branches, commits, and the pull request process.