9 min to read

Github Pages and Jekyll Notes

#Plan #Docs #Jekyll

This is the site operating manual for this repo.

What This Site Is

Folder Structure (Practical View)

.
|- _posts/              # All posts (markdown)
|- pages/               # Standalone pages (about, plan)
|- _layouts/            # Page/post/list layout templates
|- _includes/           # Reusable partials (header, footer, cards, etc.)
|- _sass/               # SCSS partials
|- assets/              # Built/static assets served by Jekyll
|- src/
|  |- yml/              # Source config split into multiple yml files
|  |- js/main/          # Source JS bundled into assets/js/scripts.min.js
|  |- js/preview/       # Preview/admin widget JS copied as-is
|  `- img/              # Source images for optimization task
|- index.html           # Home page front matter entrypoint
|- contact.html         # Contact page front matter entrypoint
|- tags.html            # Tags page front matter entrypoint
|- search.json          # Search index generated from posts
|- sitemap.xml          # Sitemap template
|- _config.yml          # Generated final Jekyll config (do not hand-edit)
`- gulpfile.js          # Build orchestration

Which Layouts Exist and When to Use Them

Current layouts in _layouts/:

Where Config Lives

Authoritative source config files are in src/yml/:

Generated config:

Key Settings You Will Actually Use

From src/yml/site.yml:

From src/yml/posts.yml:

From src/yml/advanced.yml:

From src/yml/theme.yml:

Front Matter Cheatsheet

Typical post front matter:

---
layout: post
title: "Post title"
subtitle: "Optional subtitle"
description: "Optional short summary for cards/search/SEO"
date: 2026-03-07
category: Tech
tags:
  - Tag1
  - Tag2
image: /files/path/to/image.jpg
optimized_image: /assets/img/optimized.jpg
math: true
---

Common page front matter:

---
layout: page
title: About
permalink: /about/
menu: false
---

List page front matter (layout: list_view):

---
layout: list_view
title: Project Planning
permalink: /plan/
include_tags:
  - Plan
exclude_tags: []
---

Per-page list styling overrides:

Per-page home grid overrides (layout: home):

Per-post UI overrides (layout: post):

ToC in posts:

toc: true
toc_title: Contents # optional

CSV table support in posts:

csv_url: /files/MYPROJECT/data.csv
csv_title: Data

csv_tables:
  - title: Trades
    csv_url: /files/MYPROJECT/trades.csv
  - title: Daily Stats
    csv_url: /files/MYPROJECT/daily_stats.csv

Chart config (optional):

csv_chart:
  type: line          # line, bar, or scatter
  title: Progress
  show_title: true
  show_axis_titles: true
  show_y_ticks: true
  x_tick: month       # optional month-only x tick labels
  x: Date             # column name or index
  y:
    - ForceL
    - ForceR

Expression-based chart series:

csv_chart:
  type: scatter
  x: Date
  y_label: Peak Force
  y_unit: lbs
  y_expr:
    - label: MeanForce
      expr: mean(ForceL, ForceR)
    - label: Balance
      expr: ForceL - ForceR

Chart display options:

csv_chart:
  filter:
    field: tag
    equals: Max

Weekly rollup + aggregate example:

csv_chart:
  type: line
  title: Weekly Max Peak Force
  x: Date
  group_by: week
  y_agg:
    - label: Right
      op: max
      field: peak_right
    - label: Left
      op: max
      field: peak_left

Dual-axis derived series example:

csv_chart:
  type: scatter
  y_label: Peak Force
  y_unit: lbs
  y2_label: SW
  x: Date
  group_by: week
  y_agg:
    - label: Right
      op: max
      field: peak_right
    - label: Left
      op: max
      field: peak_left
    - label: SW
      from_agg_expr: (Right + Left) / 135
      axis: right
      type: line
      color: "#f5c518"
      border_width: 4
      fill: false

Tag Strategy Reminder

Markdown Refresher

Headings:

# H1
## H2
### H3

Emphasis:

**bold**
*italic*
`inline code`

Lists:

- item
- item

1. first
2. second

Links/images:

[Link text](https://example.com)
![Alt text](/assets/img/example.jpg)

Code blocks:

```js
console.log("hello");
```

Blockquote:

> Note to self

Liquid + URL Helpers (Important)

Use these for safe URLs:

/assets/css/styles.css
/assets/css/styles.css

In templates, use:

Build / Dev Commands

Install deps:

bundle install
npm install

Run local dev:

npm run dev

One-off build:

npm run build

If Jekyll fails on Windows with _site file permission errors, close apps/processes locking files under _site/files/ and run build again.

Content Workflow (Quick)

  1. Create a markdown file in _posts/ named YYYY-MM-DD-title.md.
  2. Fill front matter (layout, title, category, tags, optional description/image).
  3. Write content in Markdown.
  4. Use Plan tag if it should appear on /plan/ instead of home.
  5. Run npm run dev and verify home, post page, search, and tags page.