scriptorium 0.6.1 → 0.7.2

data/doc/anti-amnesia/20250729-220000-user-guide-complete.md

@@ -1,41 +0,0 @@
-# User Guide Complete - 2025-07-29
-
-## Status: COMPLETE ✅
-
-The Scriptorium user guide has been completed and is located in the `doc/` directory.
-
-## Guide Structure
-
-The user guide consists of 11 sections:
-
-1. **Core Concepts** (`doc/user_guide_section_1.md`) - What is Scriptorium, LiveText, repositories, deployment
-2. **Getting Started** (`doc/user_guide_section_2.md`) - Installation, setup, basic configuration
-3. **LiveText Basics** (`doc/user_guide_section_3.md`) - **[TO BE WRITTEN BY USER]** - LiveText syntax and usage
-4. **The Front Page** (`doc/user_guide_section_4.md`) - Containers, widgets, layout configuration
-5. **Managing posts** (`doc/user_guide_section_5.md`) - Creating, editing, publishing posts
-6. **Managing Pages** (`doc/user_guide_section_6.md`) - Static pages, navigation, internal links
-7. **Customization** (`doc/user_guide_section_7.md`) - Themes, templates, widgets
-8. **Advanced Features** (`doc/user_guide_section_8.md`) - Reddit integration, social media
-9. **Deployment & Hosting** (`doc/user_guide_section_9.md`) - Local development, server deployment, SSL
-10. **Troubleshooting** (`doc/user_guide_section_10.md`) - Common issues, error messages, help resources
-11. **Reference** (`doc/user_guide_section_11.md`) - Command reference, configuration, API, file structure
-
-## Table of Contents
-
-The complete outline is documented in `doc/userdoc-toc.txt` which contains the original planning structure.
-
-## Next Steps
-
-- Section 3 (LiveText Basics) needs to be written by the user
-- Consider creating a master index file that links all sections
-- Review and refine sections as needed based on user feedback
-- Consider adding more examples and screenshots
-- May need to update sections as Scriptorium features evolve
-
-## Notes
-
-- All sections except Section 3 are complete and ready for use
-- The guide follows a logical progression from basic concepts to advanced features
-- Each section includes practical examples and step-by-step instructions
-- The reference section (Section 11) provides comprehensive technical details
-- The guide is designed to be both beginner-friendly and comprehensive for advanced users 

data/doc/anti-amnesia/20250804-213700-publishing-test-fix.md

@@ -1,49 +0,0 @@
-# Publishing Test Fix - 2025-08-04 21:37:00
-
-## Problem
-Publishing tests in `test/unit/api.rb` were failing because `post.published` timestamp was being overwritten after `publish_post` set it.
-
-## Root Cause
-1. `publish_post` correctly set `post.published` timestamp and wrote to metadata file
-2. `publish_post` called `generate_post` to generate HTML
-3. `generate_post` called `write_generated_post`, which called `write_post_metadata`
-4. `write_post_metadata` overwrote metadata file with only `vars` data, losing `post.published` timestamp
-
-## Solution
-Modified `write_post_metadata` method in `lib/scriptorium/repo.rb` to preserve existing metadata:
-
-```ruby
-private def write_post_metadata(data, view)
-  num, title = data.values_at(:"post.id", :"post.title")
-  metadata_file = @root/:posts/d4(num)/"meta.txt"
-  
-  # Read existing metadata to preserve fields like post.published
-  existing_metadata = {}
-  if File.exist?(metadata_file)
-    existing_metadata = getvars(metadata_file)
-  end
-  
-  # Prepare new metadata from data
-  new_metadata = data.select {|k,v| k.to_s.start_with?("post.") }
-  new_metadata.delete(:"post.body")
-  new_metadata[:"post.slug"] = slugify(num, title) + ".html"
-  
-  # Merge existing metadata over new metadata to preserve important fields
-  existing_metadata.each do |key, value|
-    new_metadata[key] = value
-  end
-  
-  lines = new_metadata.map { |k, v| sprintf("%-12s  %s", k, v) }
-  write_file(metadata_file, lines.join("\n"))
-end
-```
-
-## Additional Changes
-1. Removed `generate: false` parameters from all `create_post` calls in `test/unit/api.rb`
-2. Restored `publish_post` return value to return Post object as expected by tests
-3. Cleaned up debug output after confirming fix worked
-
-## Results
-- All 5 publishing tests now pass: `test_068_publish_post`, `test_069_publish_post_already_published`, `test_071_post_published_status`, `test_072_get_published_posts`, `test_073_get_published_posts_with_view`
-- Publishing functionality works correctly, preserving `post.published` timestamp through generation process
-- Remaining test failures are unrelated to publishing (view and tag management issues) 

data/doc/anti-amnesia/20250804-214400-additional-test-fixes.md

@@ -1,46 +0,0 @@
-# Additional Test Fixes - 2025-08-04 21:44:00
-
-## Problem
-After fixing the publishing tests, several other tests were failing:
-- View management tests (adding/removing views from posts)
-- Tag management tests (adding/removing tags from posts)
-- Post generation test formatting issues
-
-## Root Cause
-The fix for the publishing tests was too aggressive. The `write_post_metadata` method was preserving ALL existing metadata, including `post.views` and `post.tags`, which overwrote changes made by `update_post`.
-
-## Solution 1: Selective Metadata Preservation
-Modified `write_post_metadata` to only preserve specific fields that should not be overwritten:
-
-```ruby
-# Only preserve fields that should not be overwritten by source file changes
-fields_to_preserve = [:"post.published", :"post.deployed", :"post.created"]
-existing_metadata.each do |key, value|
-  if fields_to_preserve.include?(key)
-    new_metadata[key] = value
-  end
-end
-```
-
-This allows `post.views` and `post.tags` to be updated from the source file while preserving important system fields.
-
-## Solution 2: Metadata Formatting Consistency
-Fixed metadata formatting to be consistent across the codebase:
-- Changed from `%-12s  %s` to `%-18s  %s` to match the `Post` class format
-- Updated test to use regex `/post\.published\s+no/` instead of exact string match
-
-## Solution 3: Test Behavior Update
-Updated `test_074_create_post_without_generation` to `test_074_create_post_with_generation`:
-- The test was expecting posts to be created without generation (no `body.html`)
-- Current implementation always generates posts when created
-- Updated test to reflect actual behavior
-
-## Results
-- All 74 tests now pass
-- View management (add/remove views) works correctly
-- Tag management (add/remove tags) works correctly
-- Post generation and publishing work correctly
-- Metadata formatting is consistent
-
-## Key Insight
-The publishing fix needed to be selective about which metadata fields to preserve. Preserving all fields broke view/tag management, while preserving only system fields (published, deployed, created) allows both publishing and content management to work correctly. 

data/doc/anti-amnesia/20250804-220000-asset-function-logic-clarification.md

@@ -1,41 +0,0 @@
-# Asset Function Logic Clarification
-
-**Date**: 2025-08-04 22:00:00  
-**Topic**: Understanding the dual nature of the $$asset function  
-**Status**: Clarified
-
-## Key Insight
-
-The `$$asset` function performs **two different operations** on **two different directory structures**:
-
-### 1. Asset Search (Source/Blog Repo Tree)
-The function searches for assets in the source repository structure:
-- `posts/0001/assets/image3.jpg` (post-specific assets)
-- `views/sample/assets/image2.jpg` (view-specific assets)  
-- `assets/image1.jpg` (global assets)
-
-### 2. Asset Return (Output/Deployment Tree)
-The function returns URL paths that work in the deployed output structure:
-- `assets/0001/image3.jpg` (post assets get namespaced)
-- `assets/image2.jpg` (view assets)
-- `assets/image1.jpg` (global assets)
-
-## Why This Matters
-
-The `$$asset` function is essentially a **translation layer** between:
-- **Source structure**: Where assets are stored during development
-- **Deployment structure**: Where assets need to be for the deployed site
-
-This requires:
-1. **Asset copying**: Moving assets from source to output directories
-2. **URL translation**: Converting source paths to deployment URLs
-3. **Namespace management**: Preventing filename collisions in deployment
-
-## Implementation Implications
-
-The function must:
-1. Search the source tree to find the asset
-2. Copy the asset to the appropriate output location
-3. Return the correct URL path for the deployed site
-
-This dual nature explains why asset management is more complex than simple file lookup.

data/doc/anti-amnesia/20250806-202032-asset-function-logic-clarification.md

@@ -1,41 +0,0 @@
-# Asset Function Logic Clarification
-
-**Date**: 2025-08-04 22:00:00  
-**Topic**: Understanding the dual nature of the $$asset function  
-**Status**: Clarified
-
-## Key Insight
-
-The `$$asset` function performs **two different operations** on **two different directory structures**:
-
-### 1. Asset Search (Source/Blog Repo Tree)
-The function searches for assets in the source repository structure:
-- `posts/0001/assets/image3.jpg` (post-specific assets)
-- `views/sample/assets/image2.jpg` (view-specific assets)  
-- `assets/image1.jpg` (global assets)
-
-### 2. Asset Return (Output/Deployment Tree)
-The function returns URL paths that work in the deployed output structure:
-- `assets/0001/image3.jpg` (post assets get namespaced)
-- `assets/image2.jpg` (view assets)
-- `assets/image1.jpg` (global assets)
-
-## Why This Matters
-
-The `$$asset` function is essentially a **translation layer** between:
-- **Source structure**: Where assets are stored during development
-- **Deployment structure**: Where assets need to be for the deployed site
-
-This requires:
-1. **Asset copying**: Moving assets from source to output directories
-2. **URL translation**: Converting source paths to deployment URLs
-3. **Namespace management**: Preventing filename collisions in deployment
-
-## Implementation Implications
-
-The function must:
-1. Search the source tree to find the asset
-2. Copy the asset to the appropriate output location
-3. Return the correct URL path for the deployed site
-
-This dual nature explains why asset management is more complex than simple file lookup.

data/doc/anti-amnesia/20250813-082428-syntax-highlighting-and-navigation-improvements.md

@@ -1,256 +0,0 @@
-# Syntax Highlighting and Navigation Improvements
-
-**Date**: 2025-08-13 08:24:28  
-**Topic**: Comprehensive improvements to syntax highlighting, navigation, widgets, and user experience  
-**Status**: Implemented and tested
-
-## 🎨 **Syntax Highlighting Implementation**
-
-### **Core Changes**
-- **Replaced Prism.js** with **Rouge** (Ruby-based server-side syntax highlighter)
-- **Added `rouge` gem** dependency for syntax highlighting
-- **Added `htmlbeautifier` gem** for HTML formatting (later removed due to corruption issues)
-
-### **SyntaxHighlighter Class** (`lib/scriptorium/syntax_highlighter.rb`)
-- **Rouge integration**: Uses Rouge lexers for multiple languages (Ruby, Elixir, JavaScript, etc.)
-- **CSS generation**: Creates syntax highlighting styles that override Bootstrap constraints
-- **Class mapping**: Maps Rouge output classes to Scriptorium's semantic CSS classes
-- **Height constraints fix**: Added specific CSS rules to prevent vertical scrolling in code blocks
-
-### **CSS Overrides for Bootstrap**
-```css
-/* Override Bootstrap height constraints for syntax highlighting */
-pre code[class*="language-"] {
-  height: auto !important;
-  max-height: none !important;
-  min-height: auto !important;
-  overflow: visible !important;
-}
-
-pre:has(code[class*="language-"]) {
-  height: auto !important;
-  max-height: none !important;
-  min-height: auto !important;
-  overflow: visible !important;
-}
-```
-
-## 🔄 **Dynamic Navigation System**
-
-### **load_main Function Improvements** (`lib/scriptorium/standard_files.rb`)
-- **Post handling**: Enhanced to handle `?post=` parameters correctly
-- **Static page support**: Added support for `pages/`, `assets/`, and other static content
-- **Path resolution**: Fixed relative path issues for static pages
-- **Error handling**: Graceful fallbacks for missing content
-
-### **URL and History Management**
-- **Auto-loading**: `window.onload` automatically loads posts from URL parameters
-- **History sync**: Browser history stays synchronized with content
-- **Refresh support**: Page refreshes maintain the correct content state
-- **Navigation buttons**: "Go back" button simplified to direct link to index
-
-### **JavaScript Enhancements**
-```javascript
-// Check if this is a static page request (pages/, assets/, etc.)
-if (slug.startsWith('pages/') || slug.startsWith('assets/') || slug.includes('/')) {
-  console.log('Loading static page:', slug);
-  fetch('./' + slug)
-    .then(response => {
-      if (response.ok) {
-        return response.text();
-      } else {
-        return 'Page not found';
-      }
-    })
-    .then(content => {
-      contentDiv.innerHTML = content;
-      // Don't change URL for static pages to avoid path resolution issues
-      history.pushState({slug: slug}, "", window.location.pathname);
-    });
-  return;
-}
-```
-
-## 📁 **Pages Directory Support**
-
-### **generate_front_page Enhancement** (`lib/scriptorium/view.rb`)
-- **Pages copying**: Automatically copies `pages/` directory to output during generation
-- **Asset preservation**: Maintains file permissions and content integrity
-- **Graceful handling**: Works with or without pages directory present
-
-### **Implementation Details**
-```ruby
-# Copy pages directory to output if it exists
-pages_source = @dir/:pages
-pages_output = @dir/:output/:pages
-if Dir.exist?(pages_source)
-  FileUtils.mkdir_p(pages_output)
-  Dir.glob(pages_source/"*").each do |file|
-    next unless File.file?(file)
-    FileUtils.cp(file, pages_output/File.basename(file))
-  end
-end
-```
-
-## 🧩 **Widget System Enhancements**
-
-### **Pages Widget** (`lib/scriptorium/widgets.rb`)
-- **List-based**: Reads `list.txt` file containing page filenames
-- **Content separation**: Page content stored in `pages/` directory, not widget directory
-- **Navigation**: Generates proper links to static pages
-- **Back links**: Each page includes "← Back to Home" link
-
-### **Widget Structure**
-```
-view.dir/:widgets/"pages/list.txt"     # List of page filenames
-view.dir/:pages/"about.html"           # Actual page content
-view.dir/:pages/"contact.html"         # Actual page content
-```
-
-### **Generated HTML**
-```html
-<div class="card mb-3">
-  <div class="card-body">
-    <h5 class="card-title">
-      <button type="button" class="btn btn-primary" data-bs-toggle="collapse" data-bs-target="#pages">+</button>
-      <a href="javascript:void(0)" onclick="javascript:load_main('pages-main.html')">Pages</a>
-    </h5>
-    <div class="collapse" id="pages">
-      <li class="list-group-item"><a href="javascript:void(0)" onclick="load_main('pages/about.html')">About Us</a></li>
-      <li class="list-group-item"><a href="javascript:void(0)" onclick="load_main('pages/contact.html')">Contact</a></li>
-    </div>
-  </div>
-</div>
-```
-
-## 📋 **Clipboard Functionality**
-
-### **Clipboard Gem Integration**
-- **Added `clipboard` gem** dependency for cross-platform clipboard access
-- **Fallback support**: OS-specific commands if gem unavailable
-- **Helper methods**: `copy_to_clipboard()` and `get_from_clipboard()`
-
-### **Copy Link Button**
-- **Button text**: "Copy link" (cleaner than "Copy Permalink")
-- **Dual placement**: Added to both normal posts and permalink pages
-- **Smart URL logic**: Always copies the clean permalink URL regardless of current view
-- **Visual feedback**: Button changes to green "Copied!" for 2 seconds
-
-### **Implementation**
-```javascript
-function copyPermalinkToClipboard() {
-  // Get the current post slug from the URL or construct it
-  const currentUrl = window.location.href;
-  let permalinkUrl;
-  
-  if (currentUrl.includes('?post=')) {
-    // We're on the main blog page, construct the permalink URL
-    const postSlug = currentUrl.split('?post=')[1];
-    const baseUrl = window.location.origin + window.location.pathname.replace(/\/[^\/]*$/, '');
-    permalinkUrl = baseUrl + '/permalink/' + postSlug;
-  } else {
-    // We're already on a permalink page, use current URL
-    permalinkUrl = currentUrl;
-  }
-  
-  navigator.clipboard.writeText(permalinkUrl).then(function() {
-    // Visual feedback
-    const button = event.target;
-    button.textContent = 'Copied!';
-    button.style.background = '#28a745';
-    setTimeout(function() {
-      button.textContent = 'Copy link';
-      button.style.background = '#007bff';
-    }, 2000);
-  });
-}
-```
-
-## 🧪 **Testing Coverage**
-
-### **Unit Tests Added**
-- **View tests**: Pages directory copying functionality
-- **Widget tests**: Pages widget with back links
-- **Clipboard tests**: Clipboard helper methods
-- **Integration tests**: Full workflow verification
-
-### **Test Files Modified**
-- `test/unit/view.rb`: Added 4 new tests for pages directory handling
-- `test/unit/widgets.rb`: Added 3 new tests for Pages widget functionality
-- `test/unit/clipboard_test.rb`: New test file for clipboard functionality
-- `test/unit/repo.rb`: Enhanced permalink test to verify copy link button
-
-### **Test Patterns**
-- **Three-digit prefixes**: Following project convention (test_032, test_033, etc.)
-- **Comprehensive coverage**: Edge cases, error conditions, success scenarios
-- **Integration testing**: Full workflow from source to output
-
-## 🎯 **User Experience Improvements**
-
-### **Navigation Flow**
-1. **Main blog**: View posts with "Copy link" button
-2. **Widget expansion**: Click "+" to expand Pages widget
-3. **Page navigation**: Click page links to load static content
-4. **Back navigation**: Use "← Back to Home" links
-5. **Link sharing**: Copy clean permalink URLs from any view
-
-### **Visual Enhancements**
-- **Syntax highlighting**: Colored code blocks with proper spacing
-- **Responsive design**: Code blocks adapt to content height
-- **Interactive elements**: Collapsible widgets, copy buttons with feedback
-- **Consistent styling**: Bootstrap integration with custom overrides
-
-### **Performance Benefits**
-- **Server-side highlighting**: No client-side JavaScript processing
-- **Eliminated scrolling**: Code blocks display at full height
-- **Reduced layout shifts**: Proper height calculations prevent reflows
-- **Efficient asset handling**: Pages copied once during generation
-
-## 🔧 **Technical Architecture**
-
-### **File Organization**
-```
-lib/scriptorium/
-├── syntax_highlighter.rb    # Rouge integration and CSS generation
-├── helpers.rb               # Clipboard helper methods
-├── view.rb                  # Pages directory copying
-├── repo.rb                  # Enhanced permalink generation
-└── standard_files.rb        # Updated post templates and JavaScript
-```
-
-### **Dependencies Added**
-- `rouge` gem: Syntax highlighting
-- `clipboard` gem: Cross-platform clipboard access
-
-### **Backward Compatibility**
-- **Existing functionality**: All previous features continue to work
-- **Enhanced features**: New capabilities added without breaking changes
-- **Fallback support**: Graceful degradation when optional features unavailable
-
-## 📚 **Documentation and Examples**
-
-### **Manual Tests**
-- **`test6.rb`**: Demonstrates Pages widget with Links widget
-- **Syntax highlighting**: Shows Rouge output with proper CSS
-- **Navigation flow**: Complete user journey from index to pages
-
-### **Code Examples**
-- **Widget setup**: How to create and configure Pages widget
-- **Page creation**: HTML structure for static pages
-- **Navigation patterns**: JavaScript for dynamic content loading
-
-## 🚀 **Future Considerations**
-
-### **Potential Enhancements**
-- **Additional widgets**: More widget types following established patterns
-- **Enhanced navigation**: Breadcrumbs, sitemap generation
-- **Performance optimization**: Lazy loading, caching strategies
-- **Accessibility**: ARIA labels, keyboard navigation
-
-### **Maintenance Notes**
-- **CSS overrides**: Monitor Bootstrap compatibility on updates
-- **Clipboard API**: Consider fallback strategies for older browsers
-- **Widget system**: Extend patterns for new content types
-- **Testing**: Maintain comprehensive test coverage for new features
-
-This implementation provides a robust, user-friendly blogging system with modern syntax highlighting, intuitive navigation, and professional sharing capabilities.