How woongsnote/woongsnote-dev works
Project type and purpose
• This is a static site/blog built with Astro (a static site generator), using TypeScript and Tailwind CSS.
• Purpose: to publish technical articles (MDX content), with features like SEO, dark mode, reading-time calculation, comments (via Giscus), RSS and sitemap support.
File structure
• Top-level config:
• astro.config.mjs (Astro config)
• content.config.ts (Contentlayer or Astro content config)
• package.json, tsconfig.json, prettier.config.cjs
• public/
• fonts and other static assets
• src/
• content/ (all blog posts in .mdx)
• config/ (site-wide settings)
• layouts/ (BaseHead, BaseLayout, PostLayout)
• components/ (UI atoms, molecules, e.g. Article, Header, Footer, Tag, Toc, SocialLink, etc.)
• pages/ (Astro file-system routing: index.astro, about.astro, blog/[slug].astro, 404.astro, robots.txt, rss.xml.js)
• styles/ (global.css, typography.css)
• utils/ (data-util.ts, share-util.ts, types.ts)
• Plugins/scripts:
• remark-reading-time.mjs (reading time metadata)
• rss.xml.js, sitemap generated via Astro or plugin
README for additional insights
• The README confirms tech stack (Astro, TS, Tailwind), core features (responsive UI, SEO, dark mode, Giscus comments, sitemap, RSS).
• No pre-drawn architecture—but we know it’s an SSG pipeline with external comment service.
a. Main components
• Content Source: .mdx files under src/content
• Content Processor: Astro + content.config.ts (+ remark-reading-time plugin)
• Component Library: src/components + Tailwind CSS
• Layouts & Templates: src/layouts
• Page Router: src/pages (file-based routing)
• Asset Pipeline: src/assets + public/
• Build Engine: Astro’s build command (generates static HTML/CSS/JS)
• Third-Party Services:
• Giscus comment widget (GitHub Discussions integration)
• RSS feed generator (rss.xml.js)
• Sitemap generator (Astro plugin or custom)
• Hosting/Deployment: Vercel (or any static-host)
b. Relationships & data flow
1. MDX files → parsed by Contentlayer/config → frontmatter + AST
2. Plugins (remark-reading-time) enrich AST with metadata
3. Astro compiles pages:
• Routes in src/pages import data & components
• Layouts wrap page content
• Components render UI (Header, Article, Footer, etc.)
• Tailwind CSS applies styling
4. Build output → static assets in dist/ or public/
5. Deploy to hosting → end-user fetches static HTML/CSS/JS
6. At runtime, Giscus script loads comments widget via GitHub API
c. Architectural patterns & design principles
• Static-Site Generation (SSG) pipeline
• Component-based UI (reusable Astro components)
• File-system routing for pages
• Separation of concerns:
• Content vs. Layout vs. Presentation vs. Utilities
• Plugin-driven content transforms (remark plugins)
d. Key technologies & libraries
• Astro (core SSG framework)
• TypeScript
• Tailwind CSS (utility-first styling)
• MDX / Contentlayer (content ingestion)
• remark-reading-time (plugin)
• Giscus (comments)
• RSS & Sitemap generators
• Vercel (recommended deployment target)
Final advice
• Be very granular: show each plugin, config file, and directory group as its own node if space allows.
• Essence: content ingestion → compilation → static output → deployment → runtime widget (comments).
• Don’t over-engineer: a clear separation of content, build, and runtime is enough to convey the architecture.