Build Process

Relevant source files

The following files were used as context for generating this wiki page:

• _config.yml
• newsletters/README.md
• newsletter-program/src/core/newsletter-composer.js
• themes/matrix-flow/scripts/critical-css-extractor.js
• themes/matrix-flow/scripts/critical-css.js
• themes/matrix-flow/source/js/code-splitter.js
• src/t.txt

The build process for this portfolio is a multi-faceted system centered around the Hexo static site generator. It is heavily customized with advanced performance optimizations, including critical CSS extraction, asynchronous asset loading, and intelligent JavaScript module splitting. The process transforms Markdown source files, EJS templates, and other assets into a complete static website in the ./dist directory.

In addition to the main site build, the repository contains a separate, self-contained "Newsletter Program" with its own build and command-line tools for composing, previewing, and managing newsletters. This modular approach separates the concerns of site generation from newsletter management.

Primary Build Workflow

The main build process is initiated via an NPM script. It cleans the previous build directory, generates all static files using Hexo, and applies several custom optimization steps through Hexo's helper and script system.

The following diagram illustrates the high-level build flow:

NPM Scripts

The package.json file, which was listed as a relevant file but not provided in the context, would define the core scripts for managing the build lifecycle. Based on the build logs, the primary scripts are:

Script	Command	Description
build	npm run clean && npx hexo generate	Cleans the output directory and then generates the static site.
clean	npx hexo clean	Deletes the public (./dist) folder and the Hexo database cache.
deploy	npm run build && npx hexo deploy	Builds the site and then deploys it according to the deploy configuration in _config.yml.

Sources: src/t.txt:2-6, _config.yml:85-94

Core Configuration (Hexo)

The build process is configured through the _config.yml file at the root of the project. This file dictates how Hexo generates the site, including source and destination directories, the theme to use, and deployment settings.

Configuration Key	Value	Description
source_dir	source	The directory containing the source files (Markdown posts, pages, etc.).
public_dir	./dist	The output directory for the generated static site.
theme	matrix-flow	Specifies the theme to be used for rendering the site.
deploy	type: git	Configures deployment to a GitHub repository.
build_optimization	{...}	A custom section for build optimization settings, though its direct usage is not detailed in the provided scripts.

Sources: _config.yml:19-20, 75, 80-83, 85-94

Asset Optimization

A significant part of the build process is dedicated to front-end performance optimization, focusing on CSS and JavaScript.

CSS Optimization

The project employs a sophisticated strategy to optimize CSS delivery by separating critical, above-the-fold styles from non-critical ones.

Critical CSS Extraction

A custom script, critical-css-extractor.js, is responsible for identifying and extracting CSS rules required for the initial viewport rendering.

The process is as follows:

1. Read the main stylesheet (themes/matrix-flow/source/css/style.css).
2. Filter the CSS content, keeping only rules that match a predefined list of criticalSelectors.
3. The extracted critical CSS is minified.
4. The script generates an EJS partial (layout/_partial/critical-css.ejs) containing the critical CSS within a <style> tag, which is then inlined into the <head> of the HTML.
5. It also generates helper functions for loading the remaining non-critical CSS asynchronously.

This is the flow of the critical CSS extraction:

The selectors identified as critical include base layout, header, navigation, and keyframe animations to prevent Flash of Unstyled Content (FOUC).

// A partial list of critical selectors
this.criticalSelectors = [
    // Layout structure
    'html', 'body', '*',
    '.fullscreen-container',
    '.responsive-grid',
    '.site-header',
    
    // Critical visual elements
    '.logo-glitch',
    '.main-nav',
    '#matrix-canvas',
    
    // Essential animations and transitions
    '@keyframes scan',
    
    // Critical responsive breakpoints
    '@media (max-width: 768px)'
];

Sources: themes/matrix-flow/scripts/critical-css-extractor.js:20-45

Asynchronous Loading and Resource Hints

The critical-css.js script registers Hexo helpers to manage asset loading:

• critical_css(): Inlines the extracted critical CSS.
• non_critical_css(href): Generates <link rel="preload"> tags to load non-critical stylesheets asynchronously after the page has started rendering.
• resource_hints(): Creates <link> tags for dns-prefetch, preconnect, preload, and prefetch to instruct the browser to fetch critical resources early, further improving load times.

Sources: themes/matrix-flow/scripts/critical-css.js:100-141

JavaScript Bundling and Code Splitting

The project uses a CodeSplitter class to manage JavaScript loading. This system registers different JS modules with associated metadata, such as priority and dependencies, and loads them intelligently.

Module Registry

Modules are registered with a priority level (critical, high, medium, low) and a potential load trigger (interaction, scroll, idle).

Module	Priority	Load Trigger	Description
viewport-manager	critical	Immediate	Manages responsive layout and viewport detection.
matrix-animation	critical	Immediate	Handles the background canvas animation.
newsletter	high	interaction	Manages the newsletter subscription form.
lazy-loader	medium	scroll	Lazy-loads images using Intersection Observer.
performance-analytics	low	idle	Gathers and reports performance metrics.

Sources: themes/matrix-flow/source/js/code-splitter.js:25-63

Loading Strategy

The CodeSplitter class implements several loading strategies:

1. Critical Loading: Modules marked as critical are loaded immediately using an async script tag.
2. Interaction Preloading: Modules with loadTrigger: 'interaction' are preloaded when the user first interacts with the page (e.g., mousedown, touchstart).
3. Viewport-based Loading: Modules can be associated with specific HTML elements via a data-modules attribute and are loaded only when the element enters the viewport.
4. Idle Loading: Low-priority modules are loaded when the browser is idle, using requestIdleCallback.

This ensures that essential JavaScript is loaded first, while deferring less critical code to avoid blocking the main thread and improve perceived performance.

Sources: themes/matrix-flow/source/js/code-splitter.js:100-108, 203-221, 237-260, 263-281

Newsletter Generation

The repository includes a separate system for creating and managing newsletters, located in the newsletter-program/ directory. This system has its own "build" process for generating HTML previews from Markdown files.

The workflow is triggered by CLI commands defined in newsletters/README.md.

Newsletter Composition Flow

The NewsletterComposer class is the core of this system. When a user runs the preview command, the following sequence occurs:

This process uses Markdown files with YAML frontmatter for content and metadata, and substitutes the rendered HTML into a main email template. This allows for consistent branding and structure across all newsletters.

Sources: newsletters/README.md:16-34, newsletter-program/src/core/newsletter-composer.js:58-74