TowardsLight

TowardsLight (拾光集) is an Astro 7 static site template for personal writing that compiles Markdown posts, site configuration, links, and images through a single build pipeline. It runs on Node.js 22.23.4 or newer, outputs a static site to dist/, and is released under the MIT license by the iceforYuri GitHub account.

What is TowardsLight?

TowardsLight is a static personal publishing system built on Astro 7 that separates content boundaries, the Markdown compile chain, and visual state into three layers. It takes a profile directory (posts, site config, links, images) as input and produces a static site in dist/ with RSS, a sitemap, social cards, and structured data. It runs on any static host, with a public demo at towardslight.vercel.app.

What makes TowardsLight stand out?

• Astro 7 stack — pages, layouts, components, and plugins live under src/, with semantic design tokens in src/styles/global.css; npm run build runs astro check before the production build.
• Profile system — content is resolved from SITE_PROFILE_DIR, then a root personal/ directory containing site.ts, then the built-in src/profiles/showcase/ example. site.ts, links.ts, and posts/ are required; images/ is optional.
• Markdown pipeline — remark-math plus KaTeX 0.16.47 renders math at build time with zero formula runtime; Mermaid diagrams render in Playwright Chromium as hand-drawn light and dark SVG pairs.
• Callouts — five semantic types (NOTE, TIP, IMPORTANT, WARNING, CAUTION) with custom titles and +/- markers controlling native details state.
• Article images — Astro asset pipeline with automatic alt-text captions, missing-image SVG placeholders with original-path warnings, and WebP derivatives for large site images.
• Reading aids — a table of contents that expands with reading position, reading progress, image lightbox with keyboard controls, and code blocks with Shiki light/dark tokens and copy buttons.
• Theme and navigation — a pre-paint inline script picks between localStorage, the profile default theme, and system color; View Transition soft navigation carries theme and page type into the new document.
• Search and publishing — Fuse.js full-text search with shortcut invocation, full-site prefetch on load, RSS, sitemap, and share cards.

Who is it for?

• Writers who want content and theme in separate repos: keep posts in a standalone Git repository and upgrade the template without merging private articles.
• Technical bloggers: write posts with math, Mermaid diagrams, callouts, and code blocks that render statically.
• Developers starting a new blog from scratch: run npm run new-profile -- <directory> to scaffold site.ts, links.ts, posts/, images/, a first draft, and a CI build-check workflow.

Use cases

• Math and diagram-heavy posts: authors write frontmatter (title, description, pubDate, category, tags, draft, cover, featured) and get build-time KaTeX and dual-theme Mermaid output.
• Side-by-side comparison of two content sets: create a second git worktree for another profile, since one working copy serves one profile at a time.
• Subpath deployments: set SITE_BASE so canonical URLs, RSS, sitemap, internal links, and structured data all use the same base.

How does TowardsLight work?

1. Clone the repo, run npm install, and start npm run dev on port 4321.
2. Without an explicit profile, the built-in showcase example is used.
3. Switching profiles rebuilds symlinks, validates the target directory, and clears the Astro content cache; restart the dev server afterward.

FAQ

Is TowardsLight free?

Yes. The repository is MIT licensed, so you can use, modify, and redistribute the template. The Markdown toolchain, Fuse.js, and Lucide icons carry their own licenses from their respective authors.

What Node.js version does it need?

Node.js 22.23.4 or newer, which Astro 7 requires as its runtime. The quick-start instructions have you clone the repo, install dependencies, then run npm run dev for a local server at http://localhost:4321.

Does it need a database or CMS?

No. Posts are Markdown files in the active profile's posts/ folder, and site details live in site.ts; there is no external CMS dependency. A companion VS Code extension (TowardsLight_extension) manages posts and config from the editor sidebar.

What happens if a referenced image is missing?

A remark and Vite sentinel layer replaces the image with an SVG placeholder and warns about the original path, so a build does not silently render a broken image. npm test covers image-sentinel and callout tests.