Theme 'matrix-flow' Overview

Relevant source files

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

• themes/matrix-flow/_config.yml
• themes/matrix-flow/README-newsletter.md
• themes/matrix-flow/scripts/critical-css-extractor.js
• themes/matrix-flow/scripts/critical-css.js
• themes/matrix-flow/source/css/style.css
• themes/matrix-flow/CSS-INTEGRATION-README.md
• themes/matrix-flow/_css-config.yml
• newsletters/README.md
• newsletter-program/src/core/newsletter-composer.js
• _config.yml
• themes/matrix-flow/source/css/main.css

The matrix-flow theme is a Hexo theme designed with a distinct "Matrix" digital rain aesthetic. It features a responsive, fullscreen CSS Grid layout and is heavily focused on performance optimization through techniques like critical CSS extraction and asynchronous loading of non-critical assets. The theme also integrates a newsletter subscription system that leverages GitHub Issues for managing subscribers.

This document provides a technical overview of the theme's architecture, styling, configuration, performance features, and the integrated newsletter system. The primary goal is to offer a simple, performant, and reliable user experience without the complexities of CSS preloading.

Sources: themes/matrix-flow/CSS-INTEGRATION-README.md, themes/matrix-flow/source/css/style.css, _config.yml:83

Architecture and Layout

The theme is built upon a responsive, fullscreen layout managed by CSS Grid. This approach ensures the layout adapts smoothly across various screen sizes and orientations.

Sources: themes/matrix-flow/source/css/style.css:60-80, themes/matrix-flow/tests/fullscreen-layout-performance.test.js:130-141

CSS Grid Structure

The core layout is defined by the .responsive-grid class, which organizes the page into four main areas: header, main, sidebar, and footer.

/* themes/matrix-flow/source/css/style.css:67-76 */
.responsive-grid {
  display: grid;
  width: 100%;
  height: 100%;
  grid-template-areas: 
    "header header header"
    "main main sidebar"
    "footer footer footer";
  grid-template-rows: auto 1fr auto;
  grid-template-columns: 2fr 1fr 300px;
}

Sources: themes/matrix-flow/source/css/style.css:67-76

This diagram illustrates the desktop grid layout.

Responsive Breakpoints

The grid layout adapts at specific breakpoints to provide an optimal viewing experience on tablets and mobile devices.

• < 1200px: The layout shifts to a two-column design.
• < 768px: The layout stacks into a single column, with main, sidebar, and footer appearing sequentially.

/* themes/matrix-flow/source/css/main.css:122-135 */
@media (max-width: 768px) {
  .fullscreen-container {
    grid-template-areas: 
      "header"
      "main"
      "sidebar"
      "footer";
    grid-template-columns: 1fr;
    grid-template-rows: auto 1fr auto auto;
  }
  
  .sidebar {
    border-left: none;
    border-top: 2px solid var(--border-color);
    max-height: none;
  }
}

Sources: themes/matrix-flow/source/css/main.css:122-135, themes/matrix-flow/source/css/style.css:83-97

Styling and Aesthetics

The theme's visual identity is defined by its "Matrix" aesthetic, achieved through a specific color palette, typography, and animations.

Core Styles

Core visual elements are controlled by CSS custom properties (variables) defined in the :root.

Variable	Default Value	Description
--matrix-green	#00FF41	Primary text and highlight color.
--dark-green	#008F11	Border and secondary element color.
--background-black	#000	Main background color.
--font-family	'VT323', monospace	The primary font for the theme.
--scan-line-color	rgba(0, 0, 0, 0.3)	Color for the animated scan line effect.

Sources: themes/matrix-flow/source/css/style.css:5-13, themes/matrix-flow/source/css/main.css:3-15

Animations

The theme uses several keyframe animations to enhance its aesthetic:

• @keyframes scan: Creates a subtle, moving horizontal line effect over the entire page to mimic an old CRT monitor.
• @keyframes glitch-anim-1 & glitch-anim-2: Used on the .logo-glitch element to create a distorted, "glitching" text effect.

Sources: themes/matrix-flow/source/css/style.css:33-36, themes/matrix-flow/source/css/style.css:131-163

Configuration

The theme is configured through two main YAML files: _config.yml for theme-specific settings and _css-config.yml for styling and performance options.

Theme Configuration

The main theme settings are managed in themes/matrix-flow/_config.yml.

Setting	Type	Description
social	Object	Social media links (github, linkedin, email) for the footer.
glitch_text	String	Text to display in the animated glitch-effect logo.
menu	Object	Defines the navigation menu links.
newsletter	Object	Configuration for the newsletter subscription widget.

An example configuration is shown below:

# themes/matrix-flow/_config.yml:5-28
# Social links that appear in the footer
social:
  github: alphaleadership 
  linkedin: thomas-iniguez-visioli/
  email: thomas.iniguez@free.fr

# Glitch effect text on the home page
glitch_text: 'PORTFOLIO'

# Navigation menu
menu:
  Home: /
  Archives: /archives
  veille: https://feed-blush.vercel.app/

# Newsletter configuration
newsletter:
  github_owner: thomas-iniguez-visioli
  github_repo: portfolio
  use_github_redirect: true
  enabled: true
  position: sidebar

Sources: themes/matrix-flow/_config.yml:5-28

CSS Configuration

CSS build and optimization behavior is defined in themes/matrix-flow/_css-config.yml. This file controls minification, critical CSS inlining, and conditional CSS loading.

Setting	Description
main_css	Defines the primary CSS file and its minification/inlining behavior.
conditional_css	Specifies CSS files to be loaded only if certain conditions are met (e.g., newsletter enabled).
critical_css	Configures which parts of the CSS are considered "critical" and inlined.
optimizations	Toggles for minification, variable optimization, and media query grouping.

Sources: themes/matrix-flow/_css-config.yml

Performance Optimization

A key feature of matrix-flow is its focus on front-end performance, primarily through an advanced CSS handling strategy. The goal is to eliminate Flash of Unstyled Content (FOUC) and improve rendering times by inlining critical CSS and deferring non-critical styles.

Sources: themes/matrix-flow/CSS-INTEGRATION-README.md, themes/matrix-flow/scripts/critical-css-extractor.js

Critical CSS Extraction

The theme uses a CriticalCSSExtractor class to automate the process of identifying and extracting "above-the-fold" CSS rules.

This diagram shows the class structure for the CSS extractor.

The extraction process identifies essential selectors needed for the initial viewport render.

• Critical Selectors: html, body, .fullscreen-container, .logo-glitch, #matrix-canvas, and keyframe animations.
• Process: The script reads the main stylesheet, filters rules matching the critical selectors, minifies the result, and generates an EJS partial (critical-css.ejs) to be inlined in the <head> of the HTML.
• Non-Critical CSS: A helper is generated to load the remaining styles asynchronously.

Sources: themes/matrix-flow/scripts/critical-css-extractor.js:22-50, themes/matrix-flow/scripts/critical-css.js:20-53

This flowchart illustrates the CSS optimization build process.

Resource Hints

To further optimize loading, the theme generates helpers for resource hints, including preload, prefetch, and preconnect, which instruct the browser to fetch critical resources early.

Sources: themes/matrix-flow/scripts/critical-css.js:113-134, themes/matrix-flow/scripts/critical-css-extractor.js:166-190

Newsletter System

The theme includes a newsletter subscription widget that integrates with a repository-based management system. The system uses GitHub Issues as a lightweight, auditable "database" for new subscriptions.

Sources: themes/matrix-flow/README-newsletter.md, newsletters/README.md

Subscription Flow

1. A user fills out the newsletter form on the portfolio site.
2. The form submission redirects the user to create a new GitHub Issue in the configured repository. The issue body is pre-filled with the user's subscription details.
3. A GitHub Action is triggered, which processes the new issue, extracts the data, encrypts the email address, and stores it.
4. A welcome email is sent to the user.
5. The issue is automatically closed and scheduled for deletion to protect user privacy.

Sources: themes/matrix-flow/README-newsletter.md:38-51, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js:46-72

This sequence diagram shows the user subscription process.

Configuration

The newsletter widget is enabled and configured in themes/matrix-flow/_config.yml.

# themes/matrix-flow/_config.yml:19-28
newsletter:
  # GitHub repository for issue-based subscriptions
  github_owner: thomas-iniguez-visioli
  github_repo: portfolio
  
  # Use GitHub redirect method (true) or API endpoint (false)
  use_github_redirect: true
  
  # Widget placement
  enabled: true
  position: sidebar  # sidebar, footer, or header

Sources: themes/matrix-flow/_config.yml:19-28