Graduate Texts in Minecraft

Community-driven online textbook on Technical Minecraft.

Tutorials, explanations on game mechanics, and source-code reading. Collaboratively written and openly reviewed.

Visit the Site · Browse Raw Articles · More GTMC Projects

English | 汉语

---

About

Graduate Texts in Minecraft (GTMC) is an open, community-driven knowledge base for the technical side of Minecraft — redstone, game mechanics, and engine internals. It serves three kinds of writing:

• >> TUTORIALS — step-by-step walkthroughs for builders.
• >> EXPLANATIONS — first-principles writeups of in-game mechanics.
• >> CODE ANALYSIS — annotated readings of the game's source.

The site is built around a blueprint / scientific drafting visual language: thin blue-gray rules, square geometry, monospace HUD labels, corner brackets, and motion that feels like UI instrumentation rather than ornament. See DESIGN.md for the full system.

Note

This repository hosts the website only. Articles live in a separate repository and are pulled in as a Git submodule. All other org repos are at github.com/orgs/gtmc-dev.

Development

Tech stack

Layer	Choice
Framework	Next.js 16 (App Router, Cache Components) on React 19
Language	TypeScript 6
Styling	Tailwind CSS v4, custom tech-* blueprint tokens
Motion	motion (Framer Motion successor)
Auth	NextAuth v5 (GitHub provider) + Prisma adapter
Data	Prisma 7 against Supabase Postgres
Content	Markdown + remark/rehype, KaTeX math, Shiki code, gray-matter
Editor	CodeMirror 6 (markdown, autocomplete, merge view)
Schematics	schematic-renderer + Three.js
Search	MiniSearch
i18n	next-intl (en, zh)
Hosting	Vercel (Speed Insights, Analytics, Blob)
Lint / Format	oxlint, Prettier (with Tailwind plugin)
Tests	Vitest, Playwright, Lighthouse CI

Setup

git clone https://github.com/gtmc-dev/gtmc.git
cd gtmc
pnpm install   # also initializes articles/ when the submodule is missing
cp .env.example .env   # fill in GitHub OAuth, database URL, etc.
pnpm dev

The dev server runs on http://localhost:3000.

Scripts

pnpm dev              # Start the dev server
pnpm build            # Generate manifest + content + PDF, then `next build`
pnpm typecheck        # tsc --noEmit
pnpm lint             # oxlint
pnpm style            # prettier --check
pnpm lighthouse       # Run Lighthouse CI locally

Layout

.
├── app/                    Next.js App Router (locale-scoped routes)
│   └── [locale]/
│       ├── (public)/       Articles, public pages
│       ├── (private)/      Drafts, review hub, profile, admin
│       ├── (auth)/         GitHub sign-in flow
│       └── _homepage/      Hero card, foreground/background layers
├── components/ui/          TechCard, TechButton, CornerBrackets, …
├── lib/                    Article pipeline, auth, db, search, GitHub helpers
├── articles/               Article content (Git submodule, see below)
├── scripts/                Manifest, content, and PDF generators
├── messages/               i18n catalogs (en.json, zh.json)
├── schema.prisma           Database schema
└── DESIGN.md               Visual system reference

Submodule

The articles/ directory is a Git submodule pinned to a specific commit of the articles repo. It is not auto-updated by pnpm install once it exists.

pnpm articles:status                # Show submodule status
pnpm articles:init                  # Reinitialize at the pinned commit
pnpm articles:update                # Pull the latest articles commit

pnpm generate:manifest              # Rebuild the article manifest
pnpm generate:content               # Re-render rendered content
pnpm articles:pdf                   # Re-render the offline PDF

Important

To deploy newer article content, commit the updated submodule pointer in this repo. Vercel checkouts use whatever commit is pinned here.

For details and contribution guidance, see CONTRIBUTING.md.

See also

All articles (including drafts and pending submissions) are located in this repo: gtmc-dev/articles

---

_{Code: Apache-2.0 · Articles: CC BY-NC-SA 4.0}