jekyll-theme-zer0 0.15.0 → 0.16.0

data/_data/README.md

@@ -1,31 +1,433 @@
-## Getting Started
+# 📊 Zer0-Mistakes Data Directory
 
-These instructions will help you understand the data files in this 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.
 
-### Raw Data
+## 📁 Directory Contents
 
-The `raw` directory contains the raw data files. These files are the original data and have not been processed or manipulated in any way.
+| File | Purpose | Auto-Generated |
+|------|---------|----------------|
+| `navigation/` | Site navigation menus | No |
+| `authors.yml` | Author profile information | No |
+| `content_statistics.yml` | Site content analytics | **Yes** |
+| `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 |
 
-### Processed Data
+---
 
-The `processed` directory contains the data files that have been processed and are ready for analysis. These files have been cleaned, manipulated, or otherwise processed from the raw data files.
+## 📂 Navigation
 
-## Contributing
+### `navigation/`
 
-Please read [CONTRIBUTING.md](url) for details on our code of conduct, and the process for submitting pull requests to us.
+Contains YAML files for site navigation menus (sidebar, header, footer).
 
-## Authors
+**Example structure:**
+```yaml
+# navigation/main.yml
+- title: Home
+  url: /
+  icon: bi-house
+- title: Documentation
+  url: /docs/
+  icon: bi-book
+  children:
+    - title: Getting Started
+      url: /docs/getting-started/
+```
 
-- **Your Name** - _Initial work_ - [YourGithub](url)
+---
 
-See also the list of [contributors](url) who participated in this project.
+## 👤 Authors
 
-## License
+### `authors.yml`
 
-This project is licensed under the MIT License - see the [LICENSE.md](url) file for details
+Defines author profiles for multi-author sites.
 
-## Acknowledgments
+**Structure:**
+```yaml
+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
+```
 
-- Hat tip to anyone whose code was used
-- Inspiration
-- etc
+**Usage in posts:**
+```yaml
+---
+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`.
+
+**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:**
+```liquid
+{% 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:**
+```yaml
+# 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:**
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+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:**
+```yaml
+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:**
+```liquid
+{% 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:**
+```yaml
+- 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:**
+```yaml
+---
+prerequisites:
+  - git-basics
+  - docker-fundamentals
+---
+```
+
+**Usage in templates:**
+```liquid
+{% 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:**
+```yaml
+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:**
+```yaml
+category_to_section:
+  "ai & machine learning": ai-machine-learning
+  "artificial intelligence": ai-machine-learning
+  "devops": devops
+  "docker": devops
+```
+
+**URL Pattern:**
+```yaml
+url_pattern: "/:categories/:year/:month/:day/:title/"
+```
+
+---
+
+## 🔄 Automation Workflows
+
+### Setting Up Automated Statistics
+
+1. **Copy the workflow file:**
+   ```bash
+   cp _data/github-actions-example.yml .github/workflows/update-statistics.yml
+   ```
+
+2. **Ensure scripts are executable:**
+   ```bash
+   chmod +x _data/generate_statistics.sh
+   chmod +x _data/update_statistics.sh
+   ```
+
+3. **Customize triggers** in the workflow file as needed.
+
+4. **Push to main branch** to enable the workflow.
+
+### Manual Statistics Update
+
+```bash
+# 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`:
+```yaml
+focus_areas:
+  my_new_area:
+    - keyword1
+    - keyword2
+    - keyword3
+```
+
+### Adding New Languages
+
+Add a new language block to `ui-text.yml`:
+```yaml
+ja:  # Japanese
+  skip_links: "メインコンテンツへスキップ"
+  menu_label: "メニュー"
+  # ... translate all labels
+```
+
+### Adding New Prerequisites
+
+Edit `prerequisites.yml`:
+```yaml
+- id: my-prerequisite
+  title: "My New Prerequisite"
+  description: "Description of what this covers"
+  level: beginner  # beginner|intermediate|advanced|expert
+  category: my-category
+```
+
+---
+
+## 📋 Best Practices
+
+1. **Never edit `content_statistics.yml` manually** - it will be overwritten
+2. **Keep `statistics_config.yml` updated** when adding new content types
+3. **Test configuration changes locally** before pushing
+4. **Use consistent language codes** in `ui-text.yml`
+5. **Keep prerequisite IDs kebab-case** for URL friendliness
+6. **Validate YAML syntax** before committing:
+   ```bash
+   ruby -ryaml -e "YAML.load_file('_data/your-file.yml')"
+   ```
+
+---
+
+## 🤝 Contributing
+
+When modifying data files:
+
+1. Follow existing YAML formatting conventions
+2. Test changes locally with `bundle exec jekyll serve`
+3. Run statistics generation to verify no errors
+4. Update this README if adding new files or features
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for full guidelines.
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.