How filecoin-project/specs works
Project Type and Purpose
• This is the Filecoin Specification repository: a Hugo-based static documentation site paired with a small dynamic API (Cloudflare Worker).
• Purpose: serve the “single source of truth” spec as a fast, searchable, versioned website and API.
File-Structure Analysis
• Top-Level Directories
• content/ – Markdown spec pages (organized by section)
• layouts/ & themes/book/ – Hugo templates & partials for rendering
• api/ – Node.js code (router.js, get.js) bundled via webpack, configured by wrangler.toml for Cloudflare Workers
• config.toml, package.json – Hugo & Node build config
• Patterns
• Static site generator (SSG) for HTML/CSS/JS
• Mono-repo with “frontend” (Hugo) and “backend” (Worker)
• CI/CD via GitHub Actions (/.github/workflows/main.yml) and Fleek (/.fleek.json)
README Insights
• Confirms Hugo static-site build with live-reload (npm start)
• CI badge → auto-deploy on merge
a. Main Components
1. Developer & GitHub
2. CI/CD Pipeline (GitHub Actions + Fleek)
3. Build System
• Hugo Engine (reads content/, layouts/, assets/)
• Webpack → bundles api/src → Cloudflare Worker script
4. Deployment Targets
• Static Site → Fleek/IPFS (via .fleek.json) + CDN
• API Worker → Cloudflare Workers (via wrangler.toml)
5. End Users’ Browsers
• Static HTML/CSS/JS served from CDN
• JavaScript calls to /api endpoints
b. Relationships and Data Flows
• Dev push → GitHub
• GitHub Actions triggers:
• Hugo builds → emits static assets → deploy to Fleek/IPFS
• Webpack builds API bundle → deploy to Cloudflare Workers
• Browser fetches static content from CDN
• Browser invokes API endpoints for search or dynamic data
c. Architectural Patterns & Principles
• Clear separation: SSG for content vs. micro-service (Worker) for dynamic parts
• Content-as-code: all spec pages in markdown, compiled at build time
• Reuse of Hugo shortcodes and layouts for consistent look & feel
d. Key Technologies
• Hugo (Go-based SSG)
• SCSS/JavaScript assets with Webpack for the API
• Cloudflare Workers (API) via Wrangler
• GitHub Actions for CI
• Fleek/IPFS for static hosting + global CDN