How fmhy/edit works
1. What this repository is
- FMHY is primarily a content-driven wiki/knowledge base with a static site frontend, plus a small API layer and a separate auxiliary worker package.
- The main product is the public site at fmhy.net; the repo also supports backups, post archives, and a JSON/API-style search surface.
2. Primary source of truth: Markdown content
- The bulk of the repository lives under docs/, where the site’s pages are authored as Markdown.
- Content is organized by topic (ai, audio, gaming, video-tools, etc.), by operational pages (other/, feedback.md, privacy.md), and by chronological posts (docs/posts/*.md).
- This means the architecture is “content first”: most of the site’s structure comes from the file tree, not from a database or application backend.
3. Static site generation layer
- docs/.vitepress/ is the build system and presentation layer for the wiki.
- VitePress is extended with custom hooks, markdown transforms, and theme components to generate navigation, metadata, search UI, post pages, and special interactive pages.
- The folders hooks/, markdown/, transformer/, and theme/ show a clear separation between content processing, page generation, and UI rendering.
4. Build-time content processing
- The site uses custom build-time logic for things like:
- deriving post metadata and indexes,
- transforming Markdown syntax/shortcuts,
- generating Open Graph/RSS-related data,
- wiring “starred” and tooltip behaviors,
- supporting special blocks/components embedded in Markdown.
- docs/.vitepress/theme/posts.data.ts and the transformer files indicate that some site indexes are generated rather than hand-written.
5. Interactive frontend features inside the docs site
- The theme includes components for search, feedback, theme selection, toggles, cards, tooltips, and a “startpage” experience.
- This is still a static-site architecture, but with client-side enhancements for navigation, filtering, search, and UI personalization.
- The docs/.vitepress/theme/components/startpage/ area suggests a dedicated landing page experience with bookmarks, clock, and search bar.
6. API service boundary
- The api/ directory is a separate service, likely deployed as a worker/serverless endpoint.
- It exposes at least three concerns:
- routes/index.ts for the base API surface,
- routes/single-page.ts for page lookup/search,
- routes/feedback.post.ts for collecting user feedback.
- Middleware for CORS and rate limiting shows the API is designed for public browser access and abuse control.
7. How the site and API interact
- The static wiki is the main experience, while the API supports dynamic features that are awkward to do purely from static Markdown.
- The README explicitly points users to api.fmhy.net/single-page for finding existing entries before contributing, which implies the API backs contribution/search workflows.
- Feedback submission from the site likely posts to the API route rather than being embedded in the static site itself.
8. Separate auxiliary package: pests-repellent
- pests-repellent/ is an independent package with its own TypeScript config, worker config, and Vitest tests.
- It is structurally a separate deployable unit from the main docs site and API.
- From the naming and packaging, it appears to be a small worker/library concerned with abuse mitigation or automated request handling, not core wiki content.
9. Deployment model
- The repo is set up for multiple deployment targets:
- deploy-gh-pages.yml for the static docs site,
- deploy-api.yml for the API/worker service.
- Cloudflare-style worker configuration is present (wrangler.toml, worker-configuration.d.ts), while the docs site is built for GitHub Pages.
- This creates a clean split: static content hosting on one side, edge/API functionality on the other.
10. Repository-wide tooling and local environment
- There is strong support for reproducible development via Docker, Dev Containers, Gitpod, and Nix/Mise config.
- Formatting and content quality are enforced with Prettier, markdown linting scripts, and a typo list.
- These tools support a large editorial repository where consistency matters as much as runtime behavior.
11. Important architectural boundaries
- Content boundary: Markdown files are the authoritative wiki data.
- Presentation boundary: VitePress themes and components control how content is rendered.
- Service boundary: the API handles dynamic browser-facing capabilities and request protection.
- Deployment boundary: docs and API are deployed independently, with pests-repellent as a further separate unit.
12. Mental model for a diagram
- Draw the repo as a static documentation platform centered on docs/, with a build pipeline into a public site.
- Add a separate API/edge service that the site and contributors call for search/feedback.
- Treat pests-repellent as an adjacent worker package with its own lifecycle, not as part of the main documentation rendering path.
Main entry points: routes API routes · config.mts Site config · components Site widgets · package.json Repo tooling
Components 18
Content site
Markdown wiki content and the VitePress presentation layer that turns it into the public site.
- Wiki pages · Primary knowledge base and site pages authored in Markdown.
docs - Posts archive · Time-based announcement and update posts rendered as part of the site.
docs/posts - Site config · Top-level VitePress configuration and shared constants for the docs site.
docs/.vitepress/config.mts - Build hooks · Build-time hooks for metadata, Open Graph, RSS, and templated page generation.
docs/.vitepress/hooks - Markdown transforms · Custom Markdown processing for emoji, headers, base64 handling, and starred content.
docs/.vitepress/markdown - Content transformer · Core build-time logic that derives indexes and rewrites content for the site.
docs/.vitepress/transformer - Theme shell · Main VitePress theme entry, layouts, styles, and post rendering.
docs/.vitepress/theme - Site widgets · Interactive components for search, feedback, theme selection, toggles, tooltips, and cards.
docs/.vitepress/theme/components - Startpage · Dedicated landing experience with bookmarks, clock, and search bar.
docs/.vitepress/theme/components/startpage - Post data · Generated posts data and site-side indexes used by the theme.
docs/.vitepress/theme/posts.data.ts
Edge services
Public API surface and the separate worker package used for request handling and browser-facing dynamic features.
- API routes · Public API entrypoint exposing route handlers for browser-facing features.
api/routes - Page lookup · Single-page lookup/search endpoint used to find existing entries.
api/routes/single-page.ts - Feedback ingest · POST endpoint for collecting user feedback from the site.
api/routes/feedback.post.ts - API guards · CORS and rate limiting for the public API surface.
api/middleware - Pests repellent · Separate deployable worker/package with its own build and tests.
pests-repellent
Tooling & deploy
Repository-wide developer tooling, quality checks, and deployment configuration.
- Docs deploy · GitHub Pages deployment pipeline for the static wiki site.
.github/workflows/deploy-gh-pages.yml - API deploy · Deployment pipeline for the API/worker service.
.github/workflows/deploy-api.yml - Repo tooling · Shared local development and quality tooling including Docker, Nix/Mise, formatting, and markdown linting.
package.json
Connections 21
- Wiki pages → Site config: served by · Markdown content is built through the VitePress site configuration.
- Posts archive → Post data: indexed into · Chronological posts feed generated site indexes.
- Site config → Build hooks: loads · Configuration wires in custom build hooks.
- Site config → Markdown transforms: applies · Configuration enables custom Markdown processing.
- Site config → Theme shell: renders with · The docs site uses the custom theme shell for presentation.
- Build hooks → Content transformer: uses · Hooks rely on transformer logic for derived metadata and page generation.
- Markdown transforms → Content transformer: feeds · Markdown transforms prepare content for the transformer pipeline.
- Content transformer → Post data: generates · Build-time logic produces post data and indexes consumed by the theme.
- Theme shell → Site widgets: composes · Layouts and theme entry are built from reusable UI components.
- Site widgets → Startpage: includes · The startpage experience is implemented as a dedicated component set.
- Site widgets → Page lookup: queries · Search and lookup UI can call the API for existing entries.
- Site widgets → Feedback ingest: submits · Feedback UI posts user input to the API.
- API routes → Page lookup: routes · The API surface includes page lookup/search.
- API routes → Feedback ingest: routes · The API surface includes feedback collection.
- API routes → API guards: protected by · Public endpoints are wrapped with CORS and rate limiting.
- Wiki pages → Docs deploy: deployed by · The wiki content is published via the docs deployment workflow.
- API routes → API deploy: deployed by · API routes are published via the API deployment workflow.
- Pests repellent → API deploy: separately deployed · The auxiliary worker package has its own deployment lifecycle.
- Repo tooling → Wiki pages: supports · Repository tooling supports editorial quality and local development.
- Repo tooling → API routes: supports · Shared tooling also covers the API service.
- Repo tooling → Pests repellent: supports · Local tooling includes the separate worker package.