How golang/website works
Project Type and Purpose
• This is a monorepo for a full-stack web application: the Go project’s official content sites (go.dev, golang.org) plus the interactive Tour at go.dev/tour.
• Content (Markdown, templates, JS/TS/CSS) lives under _content/ (site content) and tour/ (tour content).
• Server binaries (Go programs) live in cmd/, supporting sites like golangorg, adminapp, adminredirect, plus the Tour server.
• Shared business logic and data handling is in internal/ packages.
Main Components
A. Content Repositories
• _content/: Markdown, templates, static assets for go.dev and golang.org
• tour/: Go Tour content, static files, frontend app (Angular-like JS)
B. Build & Asset Pipeline
• Node/NPM tools (ESLint, Stylelint, Jest) enforce formatting & test JS/TS/CSS.
• TS builds: .ts files under _content/ts are compiled/transformed to JS at runtime or build time.
C. Backend Servers (Go)
• cmd/golangorg: main combined go.dev + golang.org server
• cmd/googlegolangorg & cmd/adminapp & cmd/adminredirect: auxiliary admin and regional servers
• tour/main.go: Go Tour server
D. Internal Libraries (internal/)
• internal/web: page routing, rendering, template functions
• internal/gitfs: overlays Git content onto a virtual FS
• internal/blog, internal/talks, internal/pkgdoc, internal/tour: domain logic for each section
• internal/memcache: caching layer
• internal/api: JSON API endpoints
• internal/redirect, internal/short: URL rewriting/short URLs
E. External Services
• Google App Engine (hosting)
• Cloud Build (CI/CD)
• Google Cloud Storage or memcache for caching static data
• Gerrit (code review)
Relationships & Interactions
• Content authors update Markdown/Tmpl in _content/ or tour/.
• On go run ./cmd/golangorg, the server:
• Uses internal/gitfs to load content directly from the Git checkout
• Passes content through internal/texthtml & internal/tmplfunc to generate HTML
• Uses internal/web to route requests and render pages
• Serves static assets (CSS/JS/images) from _content subdirectories via HTTP handlers
• Executes TS transforms on the fly or via a prebuild step
• Admin servers use the same internal libraries but different content roots.
• The Tour server serves a SPA: static HTML + JS frontend (in tour/static) communicating with internal/tour API backends.
Architectural Patterns & Design Principles
• Modular monolith: multiple Go “commands” sharing internal/ libraries
• Clear separation of concerns:
• Content storage (Markdown, static assets)
• Content rendering pipeline (texthtml, tmplfunc)
• HTTP routing & server logic (web)
• Cache-aside pattern: internal/memcache caches rendered pages or data
• Virtual file system (GitFS) abstracts underlying storage from rendering code
• CI/CD via Cloud Build automatically deploys each command to App Engine
Key Elements to Label
• Asset pipeline: npx eslint, npx stylelint, npx jest, TS compiler
• Go commands: cmd/golangorg, cmd/adminapp, cmd/tour
• Shared libs: internal/web, internal/gitfs, internal/pkgdoc, internal/memcache, etc.
• External: Google App Engine, Cloud Build, Gerrit