Project Configuration
Relevant source files
The following files were used as context for generating this wiki page:The project configuration is managed through a hierarchical system of YAML files and environment variables, governing the Hexo static site generator, the matrix-flow theme, and the integrated newsletter system. This layered approach separates site-wide settings from theme-specific and feature-specific configurations.
The primary configuration files are the root _config.yml for Hexo, a theme-specific _config.yml within themes/matrix-flow/, and a dedicated _css-config.yml for styling. The newsletter feature further relies on YAML frontmatter in markdown files and environment variables for its backend processes.
Configuration Hierarchy
The configuration files are loaded in a specific order, with settings in later files potentially overriding earlier ones. The theme configuration complements the main site configuration.
This diagram shows the relationship between the main configuration files.
Main Site Configuration
The root _config.yml file contains the primary settings for the Hexo site. It defines metadata, URL structure, directories, deployment settings, and configurations for plugins and extensions.
Sources: _config.yml
Key Site Settings
| Parameter | Description | Example Value |
|---|---|---|
title | The title of the website. | portfolio |
subtitle | The subtitle of the website. | en maintenance |
author | The author's name. | thomas iniguez visioli |
language | The primary language of the site. | fr |
url | The full URL of the website. | https://thomas-iniguez-visioli.github.io/ |
public_dir | The directory for the generated static files. | ./dist |
theme | The name of the active theme. | matrix-flow |
deploy | Configuration for deploying the site, e.g., via Git. | type: git, repo, token |
Sources: _config.yml:5-12, 20, 101-110
Build and Optimization
The build_optimization section is intended to control build processes, specifying source and output files for specific tasks.
# Build Optimization
build_optimization:
timestamp_threshold: 24
source_files:
- 'data/twt.json'
output_files:
- 'source/_posts/twitter.md'
Sources: _config.yml:88-94
Theme Configuration
The matrix-flow theme has its own configuration file located at themes/matrix-flow/_config.yml. This file controls theme-specific features like social links, navigation, and the newsletter widget.
Sources: themes/matrix-flow/_config.yml
| Section | Key | Description | Example Value |
|---|---|---|---|
social | github, linkedin, email | Social media handles and contact information. | alphaleadership |
glitch_text | - | The text displayed with a glitch effect on the homepage. | PORTFOLIO |
menu | Home, Archives, etc. | Defines the navigation menu links. | /archives |
newsletter | github_owner, github_repo | Configures the GitHub repository for issue-based subscriptions. | thomas-iniguez-visioli |
newsletter | use_github_redirect | If true, redirects users to GitHub to create an issue. | true |
newsletter | enabled, position | Enables the newsletter widget and sets its location (sidebar, footer, header). | true, sidebar |
Sources: themes/matrix-flow/_config.yml:5-25, themes/matrix-flow/README-newsletter.md:16-22
Newsletter System Configuration
The newsletter system has a multi-faceted configuration involving the main Hexo config, the theme config, environment variables for secure operations, and frontmatter within each newsletter's markdown file.
Hexo Newsletter Configuration
The main _config.yml contains settings for the newsletter's backend processing.
# Newsletter Configuration
newsletter:
enabled: true
discord_webhook: ${DISCORD_WEBHOOK_URL}
retry_attempts: 3
timeout_ms: 5000
rate_limit_ms: 1000
Sources: _config.yml:80-86
Environment Variables
The newsletter program requires environment variables for secure operations, such as sending emails and encrypting subscriber data. These are typically stored as secrets in the deployment environment (e.g., GitHub Secrets).
| Variable | Description |
|---|---|
ENCRYPTION_KEY | A Base64-encoded 32-byte key for AES-256 encryption of subscriber data. |
RESEND_API_KEY | The API key for the Resend email service. |
DISCORD_WEBHOOK_URL | (Optional) The webhook URL for sending notifications to a Discord channel. |
CONTACT_EMAIL | (Optional) Contact email for GDPR requests. |
WEBSITE_URL | (Optional) The base URL for unsubscribe links. |
Sources: newsletter-program/README-SUBSCRIBER-MANAGEMENT.md:129-138, themes/matrix-flow/README-newsletter.md:29-32
Newsletter Content Frontmatter
Each newsletter is a markdown file in the newsletters/ directory and uses YAML frontmatter for its metadata and sending configuration.
| Field | Description | Type | Status |
|---|---|---|---|
subject | The email subject line. | string | Required |
date | Display date for the newsletter. | string | Required |
status | The current status of the newsletter. | draft | scheduled | sent | Required |
scheduled_at | ISO 8601 datetime for scheduled sending. | string | Optional |
website_url | Link to the main website. | string | Optional |
github_url | Link to the GitHub profile. | string | Optional |
preferences_url | Link for subscribers to manage preferences. | string | Optional |
unsubscribe_url | Link for subscribers to unsubscribe. | string | Optional |
variables | A map of custom key-value pairs for use in the template. | object | Optional |
Sources: newsletters/README.md:17-33, newsletters/newsletter-template.md:2-13
Subscription Flow Configuration
The subscription process, which creates a GitHub issue, is configured in the theme's _config.yml and uses this data to construct the issue creation URL.
This sequence diagram illustrates how the configuration is used when a user subscribes.
Asset Configuration
CSS Integration
CSS configuration is managed via themes/matrix-flow/_css-config.yml. This file defines the main CSS file and any conditional stylesheets, such as for the newsletter.
# CSS principal
main_css:
file: "/css/main.css"
minify: true
inline_critical: true
# CSS conditionnels
conditional_css:
newsletter:
file: "/css/newsletter.css"
condition: "page.newsletter || theme.newsletter?.enabled"
This configuration allows for conditional loading of CSS, optimizing performance by only including styles when they are needed.
Sources: themes/matrix-flow/CSS-INTEGRATION-README.md:80-89
Critical CSS Extraction
The project uses a script to extract critical, above-the-fold CSS to be inlined in the HTML head. The selectors considered "critical" are hardcoded within this script, acting as a form of build-time configuration.
// themes/matrix-flow/scripts/critical-css-extractor.js
this.criticalSelectors = [
// Layout structure
'html', 'body', '*',
'.fullscreen-container',
'.responsive-grid',
'.site-header',
'.site-main',
'.main-content',
// Critical visual elements
'.logo-glitch',
'.main-nav',
'.nav-item',
'#matrix-canvas',
// ... and more
];
Sources: themes/matrix-flow/scripts/critical-css-extractor.js:20-46
Summary
The project's configuration is decentralized, allowing for clear separation of concerns. Global site settings are in the root _config.yml, theme presentation is in themes/matrix-flow/_config.yml, and the complex newsletter feature uses a combination of Hexo config, theme config, environment variables, and per-file frontmatter. This modular approach supports maintainability and scalability by isolating the configuration for different parts of the system.