Jekyll Knowledge Base — Full Reference

Overview

The EZAlgo Knowledge Base is a local Jekyll site at https://knowledge.ezalgotrader.com that auto-renders Markdown files as styled HTML. A file watcher monitors source directories and auto-injects Jekyll frontmatter — you write plain Markdown, it appears on the site within seconds.

Architecture

Source MD files (no frontmatter needed)
        ↓ [inotify watcher: scripts/watcher.py]
Jekyll _posts/ dir (with auto-injected frontmatter)
        ↓ [jekyll serve --watch on port 44444]
Caddy reverse_proxy (knowledge.ezalgotrader.com)
        ↓
https://knowledge.ezalgotrader.com (HTTPS, auto-TLS)

Categories (Subdirectories)

Drop .md files into the correct subdirectory under .hermes/plans/:

Tags — The Cross-Cutting Layer

Tags come from filename keywords (hyphens/underscores split into tag boundaries). Use descriptive, topic-focused filenames to get good tags. Numeric-only tokens are excluded.

Core Platform Tags (what it does)

• trading — live trading, order execution, positions
• signals — signal generation, threshold, confluence
• backtesting — optimizer, ray, numba, historical testing
• strategy — strategy isolation, setup config, parameter management
• data-pipeline — MT5 connector, range bars, arrow, parquet, data flow
• indicators — badge values, 20 indicators, instant calculation

Frontend Tags (what users see)

• chart — scichart, rendering, WebGL, panels
• frontend — UI, panels, routes, layout, web app
• badge — badge overlay, badge values, thresholds

Backend Tags (infrastructure)

• backend — Python services, Docker, FastAPI
• rust — PyO3, range bar builder, native modules
• infra — Docker, Supabase, ports, deployment, CI/CD
• observability — logging, monitoring, health checks

Concern Tags (how we work)

• architecture — system design, data flow, big-picture decisions
• refactor — code cleanup, migration, restructuring
• security — auth, permissions, secrets
• performance — optimization, latency, throughput
• testing — TDD, test strategies

Example Filenames and Resulting Tags

Frontmatter Watcher

The watcher (/home/ezalgo/jekyll-knowledge/scripts/watcher.py) runs as jekyll-watcher.service and monitors source directories via inotifywait.

Auto-Injection Rules

• If a file lacks --- frontmatter, the watcher injects: layout, title (from first # heading), date (from YYYY-MM-DD_ prefix or mtime), categories (from subdirectory), tags (from filename keywords), author
• If a file has existing --- frontmatter, it is copied as-is — no injection

Manual Frontmatter Override

To specify exact tags, add a frontmatter block at the top of your file:

---
layout: post
title: "My Custom Title"
date: 2026-06-02
categories: [Future Features]
tags: [chart, scichart, redesign, frontend]
author: EZAlgo
---
# My content here...

Services

Commands

# Re-sync all files manually
python3 ~/jekyll-knowledge/scripts/watcher.py --sync

# Clean orphaned Jekyll files (source was deleted)
python3 ~/jekyll-knowledge/scripts/watcher.py --cleanup

# Restart services
sudo systemctl restart jekyll-knowledge jekyll-watcher

# View logs
journalctl -u jekyll-watcher -f
journalctl -u jekyll-knowledge -f

# Manual Jekyll build (no serve)
cd ~/jekyll-knowledge && bundle exec jekyll build

# Jekyll config
/home/ezalgo/jekyll-knowledge/_config.yml

# Watcher config (SOURCE_DIRS, CATEGORY_MAP)
/home/ezalgo/jekyll-knowledge/scripts/watcher.py

CATEGORY_MAP Configuration

The watcher’s CATEGORY_MAP in scripts/watcher.py maps subdirectory names to display categories:

CATEGORY_MAP = {
    "github-issues": "GitHub Issues",
    "future-features": "Future Features",
    "to-do": "To Do",
    "brainstorm": "Brainstorm",
    "documentation": "Documentation",
    "tools": "Tools",
}

Files directly in .hermes/plans/ (no subdirectory) get category plan.

Verification

After writing a file, confirm it appears at https://knowledge.ezalgotrader.com

Key Rule

Every plan, action item, brainstorm, or architectural decision MUST be published here. If it only exists in chat, it doesn’t exist.