📊 Zer0-Mistakes Data Directory¶

This directory contains YAML data files that power the Zer0-Mistakes Jekyll theme's dynamic features, including navigation, content statistics, internationalization, and content organization.

📁 Directory Contents¶

File	Purpose	Auto-Generated
`navigation/`	Site navigation menus	No
`ai.yml`	The one place the AI model is configured (read by the hub's `bamr87/bamr87/.github/actions/claude-run@main` runner, consumed by reference)	No
`ai_pricing.yml`	API list prices used to estimate AI spend for calls that report tokens but no cost (part of the shared `ai-runner` kit)	No
`authors.yml`	Author profile information	No
`content_statistics.yml`	Site content analytics	Yes
`roadmap.yml`	Single source of truth for the project roadmap (drives the README mermaid diagram and the `/roadmap/` Jekyll page)	No
`statistics_config.yml`	Statistics generation config	No
`ui-text.yml`	Multilingual UI text labels	No
`prerequisites.yml`	Educational prerequisites	No
`posts_organization.yml`	Post section mappings	No
`generate_statistics.rb`	Statistics generator script	No
`generate_statistics.sh`	Bash wrapper script	No
`update_statistics.sh`	CI/CD automation script	No
`github-actions-example.yml`	Example workflow	No

`navigation/`¶

Contains YAML files for site navigation menus (sidebar, header, footer).

Example structure:

# navigation/main.yml
- title: Home
  url: /
  icon: bi-house
- title: Documentation
  url: /docs/
  icon: bi-book
  children:
    - title: Getting Started
      url: /docs/getting-started/

👤 Authors¶

`authors.yml`¶

Defines author profiles for multi-author sites.

Structure:

john_doe:
  name: "John Doe"
  bio: "Senior Developer and Technical Writer"
  avatar: /assets/images/authors/john.jpg
  email: john@example.com
  twitter: johndoe
  github: johndoe
  website: https://johndoe.dev

Usage in posts:

---
author: john_doe
---

📈 Content Statistics¶

`content_statistics.yml` ⚡ Auto-Generated¶

Contains computed statistics about site content. Do not edit manually - this file is regenerated by generate_statistics.rb.

Build integration: Statistics refresh automatically before each build: - _plugins/content_statistics_generator.rb — Jekyll hook (local/non-safe builds) - scripts/generate-content-statistics.sh — pre-build step (GitHub Pages safe mode, validate, Docker)

Disable the Jekyll hook with content_statistics.auto_generate: false in _config.yml.

Generated metrics: - total_posts: Total number of posts - published: Published posts count - drafts: Draft posts count - categories: Posts per category - category_count: Total unique categories - tags: Posts per tag - tag_count: Total unique tags - focus_areas: Content by focus area (DevOps, Frontend, etc.) - skill_levels: Content by difficulty level - content_types: Content by type (tutorial, guide, etc.) - authors: Posts per author - content_freshness: Age distribution of content - date_range: Earliest and latest post dates - derived_stats: Calculated averages and insights - generated_at: Timestamp of generation

Accessing in templates:

{% assign stats = site.data.content_statistics %}
<p>Total posts: {{ stats.total_posts }}</p>
<p>Most posts in: {{ stats.derived_stats.most_common_category }}</p>

`statistics_config.yml`¶

Configuration for the statistics generator. Defines keyword mappings for content analysis.

Sections:

# Focus area detection keywords
focus_areas:
  devops: [docker, kubernetes, ci/cd, jenkins, terraform]
  frontend: [javascript, react, vue, css, html]
  backend: [python, node, api, database, sql]
  # ... more areas

# Skill level detection
skill_levels:
  beginner: [introduction, basics, getting started, 101]
  intermediate: [advanced basics, building, implementing]
  advanced: [optimization, architecture, scaling]
  expert: [mastering, deep dive, internals]

# Content type detection
content_types:
  tutorial: [tutorial, how-to, step-by-step, walkthrough]
  guide: [guide, handbook, manual, reference]
  # ... more types

# Display preferences
display:
  top_categories: 10
  top_tags: 20
  top_focus_areas: 8

🔧 Statistics Scripts¶

`generate_statistics.rb`¶

Ruby script that analyzes site content and generates content_statistics.yml.

Usage:

# Direct execution
ruby _data/generate_statistics.rb

# Via wrapper script
bash _data/generate_statistics.sh

Features: - Front matter parsing - Category and tag analysis - Focus area detection (via keywords) - Skill level classification - Content freshness calculation - Author statistics - Derived metrics computation

`generate_statistics.sh`¶

Bash wrapper script for statistics generation with validation and preview.

Usage:

# Generate statistics
./generate_statistics.sh

# Preview output (requires yq)
./generate_statistics.sh --preview

Features: - Ruby availability check - Configuration file validation - Content directory verification - Color-coded output - Optional preview with yq

`update_statistics.sh`¶

CI/CD automation script for running statistics updates in pipelines.

Environment Variables:

CI=true          # Indicates CI environment
AUTO_PUSH=true   # Auto-commit and push changes
FORCE_UPDATE=true # Skip hash comparison

Features: - CI environment detection - Hash-based change detection - Automatic git commit/push - Skip unchanged content - Detailed logging

`github-actions-example.yml`¶

Example GitHub Actions workflow for automated statistics updates.

Copy to .github/workflows/update-statistics.yml to enable.

Triggers: - Push to pages/_posts/**, pages/_docs/**, _data/statistics_config.yml - Manual workflow_dispatch with options - Weekly schedule (Monday 6 AM UTC)

Workflow Options: - force_update: Update even if no changes detected - skip_push: Generate but don't commit

🌐 Internationalization (i18n)¶

`ui-text.yml`¶

Multilingual UI text labels for theme components.

Supported Languages: - en - English (default) - es - Spanish - fr - French - de - German - ar - Arabic (RTL)

Structure:

en:
  # Navigation
  skip_links: "Skip to main content"
  menu_label: "Menu"
  search_label: "Search"

  # Content
  read_more: "Read more"
  table_of_contents: "Table of Contents"

  # Statistics
  stats_total_posts: "Total Posts"
  stats_published: "Published"
  # ... more labels

Usage in templates:

{% assign ui = site.data.ui-text[site.lang | default: 'en'] %}
<span>{{ ui.read_more }}</span>

📚 Educational Content¶

`prerequisites.yml`¶

Defines prerequisites for tutorials and educational content.

Structure:

- id: git-basics
  title: "Git Version Control Basics"
  description: "Understanding commits, branches, and basic git workflow"
  level: beginner
  category: version-control

- id: docker-fundamentals
  title: "Docker Container Fundamentals"
  description: "Understanding containers, images, and Docker CLI"
  level: intermediate
  category: devops

Usage in post front matter:

---
prerequisites:
  - git-basics
  - docker-fundamentals
---

Usage in templates:

{% if page.prerequisites %}
<div class="prerequisites">
  <h4>Prerequisites</h4>
  <ul>
  {% for prereq_id in page.prerequisites %}
    {% assign prereq = site.data.prerequisites | where: "id", prereq_id | first %}
    <li>{{ prereq.title }} - {{ prereq.description }}</li>
  {% endfor %}
  </ul>
</div>
{% endif %}

📂 Post Organization¶

`posts_organization.yml`¶

Configuration for post section mappings and URL patterns.

Sections:

sections:
  - id: ai-machine-learning
    title: "AI & Machine Learning"
    directory: "pages/_posts/ai & machine learning"
    icon: "bi-robot"
    color: "#8B5CF6"
    description: "Artificial intelligence, ML models, and data science"
    aliases: ["ai", "ml", "machine-learning", "artificial-intelligence"]

Category to Section Mapping:

category_to_section:
  "ai & machine learning": ai-machine-learning
  "artificial intelligence": ai-machine-learning
  "devops": devops
  "docker": devops

URL Pattern:

url_pattern: "/:categories/:year/:month/:day/:title/"

🔄 Automation Workflows¶

Setting Up Automated Statistics¶

Copy the workflow file:

cp _data/github-actions-example.yml .github/workflows/update-statistics.yml

Ensure scripts are executable:

chmod +x _data/generate_statistics.sh
chmod +x _data/update_statistics.sh

Customize triggers in the workflow file as needed.
Push to main branch to enable the workflow.

Manual Statistics Update¶

# From repository root
cd _data
ruby generate_statistics.rb

# Or using the wrapper
bash generate_statistics.sh

🛠️ Customization¶

Adding New Focus Areas¶

Edit statistics_config.yml:

focus_areas:
  my_new_area:
    - keyword1
    - keyword2
    - keyword3

Adding New Languages¶

Add a new language block to ui-text.yml:

ja:  # Japanese
  skip_links: "メインコンテンツへスキップ"
  menu_label: "メニュー"
  # ... translate all labels

Adding New Prerequisites¶

Edit prerequisites.yml:

- id: my-prerequisite
  title: "My New Prerequisite"
  description: "Description of what this covers"
  level: beginner  # beginner|intermediate|advanced|expert
  category: my-category

📋 Best Practices¶

Never edit content_statistics.yml manually - it will be overwritten
Keep statistics_config.yml updated when adding new content types
Test configuration changes locally before pushing
Use consistent language codes in ui-text.yml
Keep prerequisite IDs kebab-case for URL friendliness

Validate YAML syntax before committing:

ruby -ryaml -e "YAML.load_file('_data/your-file.yml')"

🤝 Contributing¶

When modifying data files:

Follow existing YAML formatting conventions
Test changes locally with bundle exec jekyll serve
Run statistics generation to verify no errors
Update this README if adding new files or features

See CONTRIBUTING.md for full guidelines.

📄 License¶

This project is licensed under the MIT License - see the LICENSE file for details.

📊 Zer0-Mistakes Data Directory¶

📁 Directory Contents¶

📂 Navigation¶

navigation/¶

👤 Authors¶

authors.yml¶

📈 Content Statistics¶

content_statistics.yml ⚡ Auto-Generated¶

statistics_config.yml¶

🔧 Statistics Scripts¶

generate_statistics.rb¶

generate_statistics.sh¶

update_statistics.sh¶

github-actions-example.yml¶

🌐 Internationalization (i18n)¶

ui-text.yml¶

📚 Educational Content¶

prerequisites.yml¶

📂 Post Organization¶

posts_organization.yml¶

🔄 Automation Workflows¶

Setting Up Automated Statistics¶

Manual Statistics Update¶

🛠️ Customization¶

Adding New Focus Areas¶

Adding New Languages¶

Adding New Prerequisites¶

📋 Best Practices¶

🤝 Contributing¶

📄 License¶

`navigation/`¶

`authors.yml`¶

`content_statistics.yml` ⚡ Auto-Generated¶

`statistics_config.yml`¶

`generate_statistics.rb`¶

`generate_statistics.sh`¶

`update_statistics.sh`¶

`github-actions-example.yml`¶

`ui-text.yml`¶

`prerequisites.yml`¶

`posts_organization.yml`¶