jekyll_file_wizard 0.1.0

data/bin/jekyll_file_wizard

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+require 'jekyll_file_wizard'
+
+config = JekyllFileWizard::Configuration.new
+
+# Example: Load configuration from a file
+config.load_from_file('path/to/config.yml')
+
+# Create an instance of the main functionality class with the configuration
+wizard = JekyllFileWizard::Main.new(config)
+
+# Call methods on 'wizard' to perform the desired actions
+JekyllFileWizard.run

data/docs/advanced_features.md

@@ -0,0 +1,58 @@
+# Advanced Features of JekyllFileWizard
+
+This document delves into the advanced features of the JekyllFileWizard gem. These features are designed to give users more control and flexibility over their Jekyll site management.
+
+## Dynamic HTML Structure Handling
+
+JekyllFileWizard can identify and update different sections in `index.html` and other HTML files dynamically. This feature is particularly useful for large-scale or complex Jekyll projects where manual updates can be time-consuming and error-prone.
+
+### How It Works
+
+- The gem uses Nokogiri to parse HTML files and identify sections based on specific criteria like IDs, classes, or HTML comments.
+- Users can define these criteria in the configuration file or through the CLI.
+- The gem then dynamically updates or adds sections according to the user's specifications.
+
+## Configuration Options
+
+JekyllFileWizard offers a variety of configuration options:
+
+- **Selective Updating:** Choose which sections to update or add, and their placement in the HTML structure.
+- **Feature Toggles:** Enable or disable specific functionalities as per your project needs.
+
+### Configuring Your Project
+
+To configure your project, edit the `config.yml` file in the root of your Jekyll site or specify options via the CLI. Example:
+
+```yaml
+update_sections:
+  - id: "blog-section"
+    enable: true
+  - class: "footer-links"
+    enable: false
+```
+
+## Template Management
+
+JekyllFileWizard can manage different HTML templates or layouts. This feature simplifies the process of inserting complex or repetitive HTML structures into your site.
+
+### Using Templates
+
+- Place your HTML templates in the `templates` directory.
+- Specify in the configuration which templates to use and where to insert them.
+
+## Robust Error Handling
+
+JekyllFileWizard is equipped with comprehensive error and exception handling mechanisms to manage issues such as missing files, invalid HTML, or permission problems.
+
+### Error Reporting
+
+- The gem logs detailed error messages, helping users quickly identify and resolve issues.
+- In case of critical errors, the gem halts execution to prevent further issues.
+
+## Conclusion
+
+The advanced features of JekyllFileWizard are designed to provide a robust, flexible, and user-friendly experience for managing Jekyll sites. By leveraging these features, users can significantly streamline their site management process.
+
+For more information on API reference, configuration details, and usage examples, refer to the corresponding documents in the `docs` folder.
+
+[Back to Top](#advanced-features-of-jekyllfilewizard)

data/docs/api_reference.md

@@ -0,0 +1,54 @@
+# API Reference for JekyllFileWizard
+
+This document provides a comprehensive reference to the application programming interface (API) of the JekyllFileWizard gem. It outlines the classes, methods, and their functionalities, offering a detailed guide for developers looking to extend or integrate the gem into their Jekyll projects.
+
+## Overview
+
+JekyllFileWizard is composed of several key classes, each responsible for a distinct aspect of Jekyll site management. The primary classes include:
+
+1. **HtmlUpdater:** Manages the dynamic updating of HTML files.
+2. **Configuration:** Handles the reading and application of configuration settings.
+3. **DataIntegrator:** Integrates data from Jekyll's `_data` directory into HTML files.
+
+## HtmlUpdater Class
+
+This class is responsible for parsing and updating HTML files based on the given configuration and templates.
+
+### Methods
+
+- `update_section(html_file, section_id, content)`: Updates a specific section in an HTML file.
+- `add_section(html_file, position, content)`: Adds a new section to an HTML file at the specified position.
+
+## Configuration Class
+
+Handles configuration options set by the user, either through a configuration file or via command-line arguments.
+
+### Methods
+
+- `load_config(file_path)`: Loads configuration settings from a specified YAML file.
+- `get_setting(setting_name)`: Retrieves a specific configuration setting.
+
+## DataIntegrator Class
+
+Facilitates the integration of data from Jekyll's `_data` directory into the site's HTML structure.
+
+### Methods
+
+- `integrate_data(html_file, data_file)`: Integrates data from a specified YAML data file into an HTML file.
+- `fetch_data(data_file, key)`: Fetches specific data from a YAML file based on a key.
+
+## Version Module
+
+Contains information about the current version of the gem.
+
+### Constants
+
+- `VERSION`: Holds the current version number of the JekyllFileWizard gem.
+
+## Conclusion
+
+The JekyllFileWizard API provides a robust and flexible way to manage and update Jekyll sites. By understanding and utilizing these classes and methods, developers can efficiently automate and enhance their Jekyll site management.
+
+For further information on advanced features, configuration, and usage examples, refer to the corresponding documents in the `docs` folder.
+
+[Back to Top](#api-reference-for-jekyllfilewizard)

data/docs/configuration.md

@@ -0,0 +1,59 @@
+# Configuration Guide for JekyllFileWizard
+
+This document provides detailed instructions on configuring the JekyllFileWizard gem for various use cases. It covers the configuration file structure, available options, and how to apply them effectively for customizing the behavior of the gem.
+
+## Configuration File Structure
+
+The configuration for JekyllFileWizard is managed through a YAML file, typically named `config.yml`. This file should be placed in the root directory of your Jekyll project. The structure of the file is as follows:
+
+```yaml
+# config.yml
+html_update:
+  file: index.html
+  sections:
+    - id: "#welcome-section"
+      template: "templates/welcome.html"
+    - id: "#blog-section"
+      template: "templates/blog.html"
+data_integration:
+  data_file: "_data/site_data.yml"
+  target_file: "index.html"
+interactive_cli:
+  enabled: true
+error_handling:
+  log_errors: true
+  continue_on_error: false
+```
+
+## Options
+
+### HTML Update Settings
+
+- `file`: Specifies the HTML file to be updated.
+- `sections`: A list of sections to update, each with an `id` and a `template` path.
+
+### Data Integration Settings
+
+- `data_file`: Path to the YAML data file in the `_data` directory.
+- `target_file`: The HTML file where the data should be integrated.
+
+### Interactive CLI Settings
+
+- `enabled`: Boolean value to enable or disable the interactive command-line interface.
+
+### Error Handling Settings
+
+- `log_errors`: Boolean value to turn on error logging.
+- `continue_on_error`: Boolean value to continue execution even if errors occur.
+
+## Applying Configuration
+
+To apply the configuration, ensure that your `config.yml` is correctly set up in the root of your Jekyll project. The JekyllFileWizard will automatically read this file when executed, applying the specified settings to manage your site's HTML structure and content.
+
+## Advanced Configuration
+
+For advanced users, JekyllFileWizard allows customization of more intricate aspects, such as specific data integration rules or custom CLI commands. Refer to the `advanced_features.md` document for more details.
+
+With this configuration guide, you can tailor the JekyllFileWizard to your specific needs, ensuring efficient and automated management of your Jekyll site's structure and content.
+
+[Back to Top](#configuration-guide-for-jekyllfilewizard)

data/docs/examples.md

@@ -0,0 +1,46 @@
+# Examples Documentation for JekyllFileWizard
+
+This document provides guidance and explanations for the examples included in the JekyllFileWizard gem. Each example is designed to showcase a specific functionality or use case of the gem in a Jekyll website context.
+
+## Basic Example
+
+- **Location**: `examples/basic_example`
+- **Description**: This basic example demonstrates the fundamental operation of JekyllFileWizard. It shows how to use the gem to update a simple HTML structure in a Jekyll site.
+- **Contents**:
+  - `index.html`: A basic HTML file representing a typical page in a Jekyll site.
+  - `config.yml`: A simple configuration file for JekyllFileWizard to specify the updates to be made.
+  - `header.html`, `footer.html`: Example HTML snippets to be integrated into `index.html`.
+- **Purpose**: To illustrate the primary functionality of the gem, including the replacement or insertion of HTML sections.
+
+## Advanced Example
+
+- **Location**: `examples/advanced_example`
+- **Description**: This advanced example showcases more complex use cases, such as conditional updates, handling multiple sections, and integrating content from external files.
+- **Contents**:
+  - `index_advanced.html`: A more complex HTML file with multiple sections for updates.
+  - `config_advanced.yml`: An advanced configuration file with detailed instructions for the gem.
+  - Various HTML snippet files for different sections of the site.
+- **Purpose**: To demonstrate the gem's capabilities in more complex site structures and varied update scenarios.
+
+## Data Integration Example
+
+- **Location**: `examples/data_integration_example`
+- **Description**: This example demonstrates how JekyllFileWizard can be used to integrate data from Jekyll's `_data` directory into the site's HTML files.
+- **Contents**:
+  - `_data`: Folder containing YAML data files (e.g., `team.yml`, `products.yml`).
+  - `team_section.html`, `product_catalog.html`: HTML templates that will use data from the YAML files.
+  - `config_data_integration.yml`: Configuration file to specify how data from the `_data` directory is used in the HTML templates.
+- **Purpose**: To illustrate how the gem can dynamically populate HTML sections using data from YAML files, enhancing the site's flexibility and maintainability.
+
+## How to Use the Examples
+
+1. **Setup**: Clone the repository or download the examples folder.
+2. **Explore**: Open each example folder to understand the file structure and contents.
+3. **Run JekyllFileWizard**:
+   - Navigate to the example directory in the terminal.
+   - Run the command `jekyll_file_wizard` using the provided configuration file.
+4. **Observe**: Review the changes made by the gem to the HTML files based on the configuration and data files.
+
+## Learning from Examples
+
+These examples are designed to be educational, helping users understand the practical application of JekyllFileWizard in different scenarios. By studying and experimenting with these examples, users can gain insights into how to effectively utilize the gem for their own Jekyll sites.

data/docs/getting_started.md

@@ -0,0 +1,68 @@
+# Getting Started with JekyllFileWizard
+
+Welcome to JekyllFileWizard, a gem designed to enhance your experience managing Jekyll sites. This document will guide you through the basics of getting started with JekyllFileWizard, ensuring you're well-equipped to utilize its features effectively.
+
+## Overview
+
+JekyllFileWizard automates and streamlines the management of Jekyll site files. It dynamically updates site structures, manages HTML and data files, and provides an interactive CLI for easy use. Whether you're maintaining a small blog or a large-scale Jekyll project, this gem simplifies your workflow.
+
+## Installation
+
+Before installing JekyllFileWizard, ensure you have Ruby and Jekyll installed on your system. Follow these steps to install the gem:
+
+1. **Install the Gem:**
+   ```bash
+   gem install JekyllFileWizard
+   ```
+
+2. **Verify Installation:**
+   Run the following command to ensure the gem is installed correctly:
+   ```bash
+   jekyll_file_wizard --version
+   ```
+
+## Setting Up Your Jekyll Project
+
+If you already have a Jekyll project, navigate to your project directory. If not, create a new Jekyll site:
+
+```bash
+jekyll new mysite
+cd mysite
+```
+
+## Integrating JekyllFileWizard
+
+1. **Execute the Wizard:**
+   In your Jekyll project directory, run:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+2. **Follow the Prompts:**
+   The CLI will guide you through a series of steps to configure your Jekyll site, such as updating HTML structures, managing data files, and setting up templates.
+
+## First Steps
+
+After integrating JekyllFileWizard into your Jekyll project, you can:
+
+- **Update HTML Structures:** Automatically update or add sections to your `index.html` based on templates or custom configurations.
+- **Manage Data Files:** Utilize the `_data` directory to fetch and incorporate data dynamically into your site.
+- **Use Templates:** Leverage predefined templates for common site sections.
+
+## Next Steps
+
+For detailed information on advanced features, API reference, configuration options, and more, refer to the respective documents in the `docs` folder. Here are some key documents to explore:
+
+- `advanced_features.md` for in-depth details about advanced functionalities.
+- `api_reference.md` for a complete reference to the gem's API.
+- `configuration.md` for configuring the gem to suit your specific needs.
+
+## Support and Contributions
+
+For support, troubleshooting, or contributions, please refer to `troubleshooting.md` and `README.md`. Contributions to JekyllFileWizard are always welcome!
+
+---
+
+Thank you for choosing JekyllFileWizard. We hope it enhances your Jekyll site development experience! 🚀
+
+[Back to Top](#getting-started-with-jekyllfilewizard)

data/docs/troubleshooting.md

@@ -0,0 +1,48 @@
+# Troubleshooting Guide for JekyllFileWizard
+
+This guide aims to help users troubleshoot common issues encountered while using the JekyllFileWizard gem. It provides solutions to frequent problems and advice on how to resolve them effectively.
+
+## Common Issues and Solutions
+
+### 1. Configuration File Not Found
+- **Problem**: The gem cannot locate the `config.yml` file.
+- **Solution**: Ensure the `config.yml` file is in the root directory of your Jekyll project. Check for typos in the filename or path.
+
+### 2. HTML File Update Failure
+- **Problem**: Changes are not reflected in the specified HTML file.
+- **Solution**: Confirm that the path and section IDs in `config.yml` are correct. Ensure that the HTML file is accessible and not write-protected.
+
+### 3. Data Integration Issues
+- **Problem**: Data from the `_data` directory is not correctly integrated into the HTML file.
+- **Solution**: Verify the path to the data file and the structure of the YAML data. Check that the target HTML file contains the appropriate placeholders or identifiers for data insertion.
+
+### 4. Interactive CLI Not Responding
+- **Problem**: The interactive CLI does not launch or respond to commands.
+- **Solution**: Ensure the interactive CLI is enabled in `config.yml`. Check for console errors or conflicts with other CLI tools.
+
+### 5. Error Logging Inconsistencies
+- **Problem**: Error messages are unclear or not logged as expected.
+- **Solution**: Check the `log_errors` and `continue_on_error` settings in `config.yml`. Confirm that the log file has appropriate write permissions.
+
+### 6. Template Rendering Errors
+- **Problem**: Custom templates are not rendered correctly in the HTML file.
+- **Solution**: Check the template file paths and formats. Ensure that the HTML structure in the templates is valid.
+
+### 7. Gem Installation Issues
+- **Problem**: Difficulty installing or updating the gem.
+- **Solution**: Verify Ruby and Gem environment setup. Ensure network connectivity for accessing RubyGems.org. Try updating RubyGems (`gem update --system`).
+
+## Advanced Troubleshooting
+
+For more complex issues or custom setups, refer to the `api_reference.md` and `advanced_features.md` documents for in-depth information on the gem's internal workings and advanced functionalities.
+
+## Seeking Further Assistance
+
+If you encounter an issue not covered in this guide, consider the following:
+- Check the [JekyllFileWizard GitHub repository](https://github.com/JekyllFileWizard) for known issues or discussions.
+- Consult the Jekyll community forums or relevant online communities for broader Jekyll-related issues.
+- For bugs or feature requests, open an issue on the GitHub repository.
+
+Remember, detailed error reports, including logs and configuration files, can significantly aid in resolving your issues more efficiently.
+
+[Back to Top](#troubleshooting-guide-for-jekyllfilewizard)

data/docs/usage.md

@@ -0,0 +1,77 @@
+# Usage Guide for JekyllFileWizard
+
+This document provides comprehensive instructions on how to use the JekyllFileWizard gem to manage and update Jekyll site structures effectively. It covers basic to advanced usage scenarios, ensuring you can fully leverage the gem's capabilities.
+
+## Installation
+
+1. **Install the Gem**:
+   ```bash
+   gem install jekyll_file_wizard
+   ```
+
+2. **Navigate to Your Jekyll Project**:
+   ```bash
+   cd path/to/your/jekyll/project
+   ```
+
+3. **Verify Installation**:
+   Run `jekyll_file_wizard --version` to confirm the gem is installed correctly.
+
+## Basic Usage
+
+1. **Create a Configuration File**:
+   - Name it `config.yml` and place it in the root of your Jekyll project.
+   - Define the sections of the `index.html` file you wish to update or add.
+
+2. **Run the Gem**:
+   ```bash
+   jekyll_file_wizard
+   ```
+   - The gem reads `config.yml` and makes necessary updates to your `index.html`.
+
+## Advanced Usage
+
+### Custom Templates
+
+1. **Create Custom HTML Templates**:
+   - Place them in the `templates` directory of your Jekyll project.
+   - You can create templates for sections like blog highlights, featured projects, etc.
+
+2. **Update `config.yml` to Include Templates**:
+   - Specify the template file names and their target insertion points in `index.html`.
+
+### Data Integration
+
+1. **Prepare Data Files**:
+   - Place YAML data files in the `_data` directory.
+   - Ensure the data structure matches your template placeholders.
+
+2. **Configure Data Integration in `config.yml`**:
+   - Define which data files to use and where to integrate them in `index.html`.
+
+### Interactive CLI
+
+1. **Launch Interactive Mode**:
+   ```bash
+   jekyll_file_wizard --interactive
+   ```
+   - Follow the prompts to select options and configure updates dynamically.
+
+## Routine Maintenance
+
+- Regularly run `jekyll_file_wizard` to ensure your Jekyll site stays updated with the latest content from your data files and templates.
+- Use the interactive CLI for quick adjustments or to experiment with different configurations.
+
+## Troubleshooting
+
+- Refer to the `troubleshooting.md` document for common issues and solutions.
+- For complex scenarios, consult the `api_reference.md` and `advanced_features.md` for deeper insights into the gem's functionalities.
+
+## Getting Help
+
+- Access detailed documentation and examples in the `docs` directory.
+- Visit the [JekyllFileWizard GitHub repository](https://github.com/JekyllFileWizard) for additional resources and community support.
+
+Remember, the JekyllFileWizard gem is designed to make managing your Jekyll site's structure easier and more efficient, giving you more time to focus on content creation and site design.
+
+[Back to Top](#usage-guide-for-jekyllfilewizard)

data/examples/advanced_example/advanced_examples.md

@@ -0,0 +1,91 @@
+# Advanced Examples for JekyllFileWizard
+
+This folder contains advanced examples that showcase the more complex capabilities of the JekyllFileWizard gem. These examples demonstrate how to handle intricate scenarios and leverage the gem's full potential for sophisticated Jekyll site management.
+
+## Example 1: Dynamic Content Integration
+
+**Scenario**: You want to dynamically integrate content from an external API into your Jekyll site's specific page.
+
+### Steps:
+
+1. **External API Integration Script**:
+   - File: `fetch_external_content.rb`
+   - Content: Ruby script to fetch data from an external API and format it into HTML.
+
+2. **Create a Placeholder Template**:
+   - File: `external_content_placeholder.html`
+   - Content: HTML structure with a placeholder where the dynamic content will be inserted.
+
+3. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "services.html"
+       section: "after"
+       section_id: "main-services"
+       template: "external_content_placeholder.html"
+       script: "fetch_external_content.rb"
+   ```
+
+4. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+## Example 2: Automated Blog Post Generation
+
+**Scenario**: Automatically generate blog posts from a set of markdown files stored in an external directory.
+
+### Steps:
+
+1. **Markdown Files**:
+   - Location: `external_blog_posts/`
+   - Content: Multiple markdown files with content for blog posts.
+
+2. **Blog Post Template**:
+   - File: `blog_post_template.md`
+   - Content: Markdown template with placeholders for blog post content.
+
+3. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "_posts/"
+       template: "blog_post_template.md"
+       markdown_directory: "external_blog_posts/"
+   ```
+
+4. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+## Example 3: Multi-Section Update with Data Integration
+
+**Scenario**: Update multiple sections of a page by integrating data from various YAML files in the `_data` directory.
+
+### Steps:
+
+1. **Section Templates**:
+   - Files: `section1.html`, `section2.html`
+   - Content: HTML templates for each section with placeholders for data integration.
+
+2. **Data Files**:
+   - Location: `_data/`
+   - Files: `data1.yml`, `data2.yml`
+
+3. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "about/index.html"
+       sections:
+         - template: "section1.html"
+           data_file: "data1.yml"
+         - template: "section2.html"
+           data_file: "data2.yml"
+   ```
+
+4. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+These advanced examples highlight JekyllFileWizard's ability to handle complex scenarios, including dynamic content integration, automated content generation, and multi-section updates with data integration. They are ideal for users looking to automate and streamline their Jekyll site management processes significantly.

data/examples/basic_example/basic_example.md

@@ -0,0 +1,81 @@
+# Basic Examples for JekyllFileWizard
+
+This folder contains a set of basic examples to demonstrate the usage of the JekyllFileWizard gem in various scenarios. These examples will help you understand how to apply the gem effectively in your Jekyll projects.
+
+## Example 1: Updating the Index Page
+
+**Scenario**: You want to update the `index.html` file of your Jekyll site by adding a new section for latest blog posts.
+
+### Steps:
+
+1. **Create a New HTML Template**:
+   - File: `latest_blog_posts.html`
+   - Content: HTML structure for displaying the latest blog posts.
+
+2. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "index.html"
+       section: "end"
+       template: "latest_blog_posts.html"
+   ```
+
+3. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+## Example 2: Integrating Data from `_data`
+
+**Scenario**: You have a list of team members in a YAML file and want to display it on your homepage.
+
+### Steps:
+
+1. **Data File**:
+   - Location: `_data/team.yml`
+   - Content: YAML structured data of team members.
+
+2. **Create a Team Section Template**:
+   - File: `team_section.html`
+   - Content: HTML with placeholders for team member data.
+
+3. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "index.html"
+       section: "after"
+       section_id: "about-us"
+       template: "team_section.html"
+       data_file: "team.yml"
+   ```
+
+4. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+## Example 3: Adding a Contact Form
+
+**Scenario**: You want to add a contact form to your site's contact page.
+
+### Steps:
+
+1. **Contact Form Template**:
+   - File: `contact_form.html`
+   - Content: HTML structure for the contact form.
+
+2. **Configuration File** (`config.yml`):
+   ```yaml
+   updates:
+     - target: "contact/index.html"
+       section: "before"
+       section_id: "footer"
+       template: "contact_form.html"
+   ```
+
+3. **Run JekyllFileWizard**:
+   ```bash
+   jekyll_file_wizard
+   ```
+
+These basic examples cover typical scenarios you might encounter while using JekyllFileWizard. They are designed to be straightforward and easily adaptable to your specific needs.

data/examples/config.yml

@@ -0,0 +1,23 @@
+sections:
+  blog:
+    template: blog_section
+    position: after
+    relative_element: '.welcome-message'
+  features:
+    identifier: id
+    content_path: path/to/features_content.html
+    action: update
+  blog_highlights:
+    identifier: class
+    content_path: path/to/blog_highlights_content.html
+    action: insert
+    position: after
+    relative_element: '.intro-section'
+  call_to_action:
+    toggle: off
+  sections_to_update:
+    - "features"
+    - "testimonials"
+  feature_toggles:
+    interactive_elements: true
+    latest_projects: false