Scripts Overview

Scripts — PowerShell for builds, Python CGI for the server side, totaling over twenty files. Here is a unified overview of what they do and what parameters they support, for easy reference later.

Build System (PowerShell)

The build system is the backbone of the site. Five scripts run in a fixed order: first scanning article metadata to generate archives and indexes, then stitching HTML components page by page, and finally outputting RSS and sitemap. All are located under scripts/.

Reads one content file and all HTML components (header, banner, footer, sidebars), stitching them into a complete page. Supports -Lang en for English components, -IncludeDrafts for draft builds, and -SkipArchiveRefresh to skip archive updates.

Detailed walkthrough →

Calls other scripts in order, scanning all blog posts and standalone pages to build them one by one. Supports -Force for forced full rebuild, -IncludeDrafts for drafts, and -Minify for compressed output. Built-in incremental caching — compares component hashes and file modification times to skip unchanged pages.

Detailed walkthrough →

Scans all blog post metadata (date, title, tags, draft flag), producing four output files in a single pass: latest posts component, year-month grouped archive page, tag cloud page, and plain text search index. Supports -Lang en for the English version.

Detailed walkthrough →

Generates an RSS 2.0 XML file containing channel description, article entries, plain text summaries, and GUIDs. Output goes to dist/rss.xml.

Detailed walkthrough →

Scans all blog posts, standalone pages, and static resources to generate an XML file conforming to Sitemap Protocol 0.9. Includes changefreq (update frequency) and priority (priority level), and skips draft pages. Currently covers about 50 URLs.

Detailed walkthrough →

Web Server & Tools (Python)

A custom HTTP server based on Python's built-in http.server. Supports a whitelist routing table (URL to filesystem path mapping), CGI subprocess invocation, HTTP/1.1 keep-alive, multi-threaded concurrency, static resource aggressive caching, and custom 404/403 pages. Startup parameters: nolog disables logging, nocount disables visitor counting. Listens on 0.0.0.0:81.

Automatically increments the count on homepage visits and generates an 88x31 pixel LED seven-segment animated GIF. Features a 12-frame breathing animation, scanline scrolling, and glow effects. The count is stored in data/runtime/visitor_count.txt.

Background sending script for guestbook reply notifications. Called by guestbook.py as an independent subprocess, reads SMTP configuration (from environment variables), and sends 90s-style HTML emails via QQ Foxmail. The body includes the reply content and a quote of the original message.

Reads the banned words list from data/runtime/banned_words.json, automatically replacing sensitive words with *** when messages are submitted. Supports encrypting the JSON into a .dat file for privacy protection (optional).

Scans component HTML for external image URLs, downloads them to assets/images/external/, and replaces the reference paths. Used for HTTP access on old devices (which cannot load HTTPS resources). Supports --dry-run preview mode.

Uses Pillow to generate 20 pixel-art GIF emojis (em01-em20) at 20x20 pixels, output to assets/images/emoticons/.

CGI Scripts (Python)

Handles guestbook form submissions. Parses POST data, records IP addresses, appends to the guestbook file, extracts @mentions and sends email notifications in the background, and triggers homepage rebuild. Sensitive words are automatically filtered after messages are written.

Detailed walkthrough →

Handles blog post comment form submissions. Parses POST data, appends to data/comments/{slug}.txt, asynchronously rebuilds the corresponding blog post in the background, and 302-redirects back to the comment section anchor. Supports nested replies (parent field) and IP display toggles.

Reads the search index file and performs case-insensitive full-text matching on keywords. Title matches receive boosted weight, returning result pages with highlighted snippets. Completely JavaScript-free — an HTML form submits to the CGI, and the server handles all logic.

A web-based blog post editor. Supports creating, editing, and deleting articles, a formatting toolbar (bold, italic, links, images, footnotes, tables), character counting, and live preview. Authentication is controlled via the EDITOR_TOKEN environment variable. Output is written directly to src/content/blog/.

Integrates common tools including Base64 encoding/decoding, MD5/SHA hashing, timestamp conversion, and random password generation. Pure HTML forms + CGI backend, no JavaScript required.

Generates a static statistics page (dist/stats.html). Includes an ASCII heatmap, hourly/daily distribution, monthly trends, browser/OS analysis, and a User-Agent archaeology panel. Uses the DB-IP city-level database to draw a visitor world map. Supports .gz compressed log reading and local IP filtering.

Provides a unified logging interface for all CGI scripts. Writes to corresponding files by category under data/logs/ (guestbook, editor, search, toolbox, error, etc.).

Entry Points

Call Order

rebuild-all.ps1 internally calls scripts in the following order. You don't need to memorize this, but knowing the order helps understand the data flow:

For daily use, just run .\scripts\build.cmd (incremental) or powershell .\scripts\rebuild-all.ps1 -Force (full rebuild). The server process web_server.py runs independently and doesn't need to restart with builds.