scriptorium 0.0.3 → 0.6.1

data/doc/user_guide_section_6.md

@@ -0,0 +1,147 @@
+# 6. Managing Pages
+
+Pages in Scriptorium are static HTML files that provide additional content beyond your blog posts. They're perfect for creating "About" pages, contact information, documentation, or any other static content you want to make available on your site.
+
+## Used in navbar
+
+Pages can be linked directly in your site's navigation bar. This is typically configured in the header section of your view.
+
+To add a page to your navbar:
+
+1. **Create the page file** in your view's `pages/` directory:
+   ```bash
+   scriptorium edit pages/about.html
+   ```
+
+2. **Configure the navbar** in your view's header configuration:
+   ```bash
+   scriptorium edit config/header.txt
+   ```
+
+3. **Add navigation links** to your header configuration file. The exact format depends on your theme, but typically looks like:
+   ```
+   # Navigation links
+   .nav-link "About" "pages/about.html"
+   .nav-link "Contact" "pages/contact.html"
+   ```
+
+The navbar will automatically include these links, making your pages easily accessible from any part of your site.
+
+## Used in Pages widget
+
+Pages can also be displayed using the Pages widget, which creates a sidebar or footer list of your pages. This is useful for organizing related content or providing quick access to important pages.
+
+To set up the Pages widget:
+
+1. **Create the widget configuration**:
+   ```bash
+   scriptorium edit widgets/pages/list.txt
+   ```
+
+2. **Add page references** to the list file. Each line should contain the page filename (without the `.html` extension):
+   ```
+   about
+   contact
+   documentation
+   ```
+
+3. **Generate the widget**:
+   ```bash
+   scriptorium generate widget pages
+   ```
+
+The Pages widget will automatically:
+- Extract titles from the HTML files (using `<title>` tags or `<h1>` tags)
+- Create clickable links to each page
+- Skip any pages that don't exist (with a warning)
+
+## Internal links
+
+Pages can link to each other and to blog posts using internal links. This creates a connected web of content within your site.
+
+### Linking between pages
+
+In your page HTML, use JavaScript-based links that work with Scriptorium's navigation system:
+
+```html
+<a href="javascript:void(0)" onclick="load_main('pages/other-page.html')">Link to Another Page</a>
+```
+
+### Linking from pages to posts
+
+You can also link from pages to specific blog posts:
+
+```html
+<a href="javascript:void(0)" onclick="load_main('posts/post-slug.html')">Link to Blog Post</a>
+```
+
+### Linking from posts to pages
+
+In your blog posts, you can link to pages using the same pattern:
+
+```html
+<a href="javascript:void(0)" onclick="load_main('pages/about.html')">About Us</a>
+```
+
+## Subdirectories under pages/
+
+For better organization, you can create subdirectories under the `pages/` directory. This is useful for grouping related pages or creating more complex site structures.
+
+### Creating subdirectories
+
+```bash
+# Create a subdirectory
+mkdir pages/documentation
+
+# Create pages within the subdirectory
+scriptorium edit pages/documentation/getting-started.html
+scriptorium edit pages/documentation/advanced-usage.html
+```
+
+### Linking to subdirectory pages
+
+When linking to pages in subdirectories, include the full path:
+
+```html
+<a href="javascript:void(0)" onclick="load_main('pages/documentation/getting-started.html')">Getting Started</a>
+```
+
+### Using subdirectories in the Pages widget
+
+In your `widgets/pages/list.txt` file, you can reference subdirectory pages using relative paths:
+
+```
+about
+contact
+documentation/getting-started
+documentation/advanced-usage
+```
+
+### Best practices for page organization
+
+- **Use descriptive filenames**: `about.html`, `contact.html`, `privacy-policy.html`
+- **Group related content**: Use subdirectories for documentation, guides, or multi-part content
+- **Keep navigation simple**: Don't create too many levels of subdirectories
+- **Use consistent naming**: Stick to lowercase with hyphens for multi-word filenames
+- **Include proper titles**: Always use `<title>` tags in your HTML for better widget integration
+
+### Page templates and styling
+
+Pages inherit the same styling as your main site, so they'll automatically match your theme. You can include additional CSS or JavaScript in individual pages if needed, but it's generally better to keep styling consistent across your site.
+
+### Managing page content
+
+Since pages are static HTML files, you can edit them using any text editor or HTML editor. Scriptorium provides convenient commands for common page operations:
+
+```bash
+# Create a new page
+scriptorium edit pages/new-page.html
+
+# List all pages in a view
+ls views/your-view/pages/
+
+# Generate all content (including pages)
+scriptorium generate
+```
+
+Pages are a powerful way to extend your Scriptorium site beyond just blog posts, allowing you to create a complete website with multiple types of content. 

data/doc/user_guide_section_7.md

@@ -0,0 +1,311 @@
+# 7. Customization
+
+Scriptorium is designed to be highly customizable while maintaining simplicity. You can modify themes, create custom templates, and extend functionality through widgets and features.
+
+## Themes and Styling (cloning)
+
+Themes in Scriptorium control the overall look and feel of your site. Currently, Scriptorium comes with a "standard" theme, but you can clone and customize it to create your own unique design.
+
+### Understanding themes
+
+A theme consists of several components:
+- **Layout templates**: HTML structure for different page types
+- **CSS styling**: Visual appearance and responsive design
+- **Configuration files**: Default settings and options
+- **Assets**: Images, fonts, and other static files
+
+### Cloning the standard theme
+
+To create your own theme:
+
+1. **Navigate to the themes directory**:
+   ```bash
+   cd themes
+   ```
+
+2. **Clone the standard theme**:
+   ```bash
+   cp -r standard my-custom-theme
+   ```
+
+3. **Update your view to use the new theme**:
+   ```bash
+   scriptorium edit config.txt
+   ```
+   
+   Change the theme line to:
+   ```
+   theme: my-custom-theme
+   ```
+
+### Customizing CSS
+
+The main styling is controlled by CSS files in your theme:
+
+- **`layout.css`**: Overall layout and responsive design
+- **`text.css`**: Typography and text styling
+- **`bootstrap.css`**: Bootstrap framework (if used)
+
+To modify the appearance:
+
+1. **Edit the CSS files** in your theme directory:
+   ```bash
+   scriptorium edit themes/my-custom-theme/layout/gen/layout.css
+   scriptorium edit themes/my-custom-theme/layout/gen/text.css
+   ```
+
+2. **Common customizations**:
+   - Change colors and fonts
+   - Modify spacing and layout
+   - Add custom animations
+   - Adjust responsive breakpoints
+
+3. **Regenerate your site** to see changes:
+   ```bash
+   scriptorium generate
+   ```
+
+### Theme structure
+
+Understanding the theme directory structure helps with customization:
+
+```
+my-custom-theme/
+├── assets/           # Images, fonts, etc.
+├── config.txt        # Theme configuration
+├── header/           # Header templates
+├── initial/          # Initial content templates
+├── layout/           # Layout templates and CSS
+│   ├── config/       # Layout configuration files
+│   ├── gen/          # Generated CSS files
+│   └── layout.txt    # Layout structure
+└── templates/        # Main templates
+    ├── index.lt3     # Front page template
+    ├── post.lt3      # Individual post template
+    └── widget.lt3    # Widget template
+```
+
+### Responsive design
+
+Scriptorium themes are designed to work on various screen sizes. When customizing:
+
+- **Mobile-first approach**: Start with mobile styles and enhance for larger screens
+- **Flexible layouts**: Use CSS Grid and Flexbox for responsive layouts
+- **Test on multiple devices**: Ensure your customizations work across different screen sizes
+
+## Templates
+
+Templates control how your content is structured and displayed. Scriptorium uses LiveText templates (`.lt3` files) that combine HTML structure with dynamic content.
+
+### Main templates
+
+The core templates in your theme:
+
+- **`templates/index.lt3`**: Front page layout
+- **`templates/post.lt3`**: Individual blog post layout
+- **`templates/widget.lt3`**: Widget container layout
+
+### Customizing post templates
+
+To modify how blog posts are displayed:
+
+1. **Edit the post template**:
+   ```bash
+   scriptorium edit themes/my-custom-theme/templates/post.lt3
+   ```
+
+2. **Available variables** in post templates:
+   - `%{post.title}`: Post title
+   - `%{post.body}`: Post content
+   - `%{post.pubdate}`: Publication date
+   - `%{post.tags}`: Post tags
+   - `%{post.blurb}`: Post excerpt
+
+3. **Example template structure**:
+   ```
+   <article class="post">
+     <header>
+       <h1>%{post.title}</h1>
+       <time>%{post.pubdate}</time>
+     </header>
+     <div class="content">
+       %{post.body}
+     </div>
+     <footer>
+       <div class="tags">%{post.tags}</div>
+     </footer>
+   </article>
+   ```
+
+### Customizing the front page
+
+The front page template controls how your blog index is displayed:
+
+1. **Edit the index template**:
+   ```bash
+   scriptorium edit themes/my-custom-theme/templates/index.lt3
+   ```
+
+2. **Common customizations**:
+   - Change the post listing format
+   - Add featured post sections
+   - Modify pagination
+   - Include custom widgets
+
+### Template inheritance and overrides
+
+You can override specific templates for individual views:
+
+1. **Create a view-specific template**:
+   ```bash
+   scriptorium edit views/my-view/templates/post.lt3
+   ```
+
+2. **The view-specific template** will be used instead of the theme template for that view
+
+### LiveText in templates
+
+Templates use LiveText syntax for dynamic content:
+
+- **Variables**: `%{variable_name}`
+- **Conditionals**: `.if condition` ... `.end`
+- **Loops**: `.each item` ... `.end`
+- **Includes**: `.include "file.lt3"`
+
+## Widgets and Features
+
+Widgets are modular components that add functionality to your site. Scriptorium comes with several built-in widgets, and you can create custom ones.
+
+### Built-in widgets
+
+#### Links widget
+
+Displays a list of external links in a sidebar:
+
+1. **Configure the widget**:
+   ```bash
+   scriptorium edit widgets/links/list.txt
+   ```
+
+2. **Add links** in the format `url, title`:
+   ```
+   https://example.com, Example Site
+   https://github.com, GitHub Profile
+   ```
+
+3. **Generate the widget**:
+   ```bash
+   scriptorium generate widget links
+   ```
+
+#### Pages widget
+
+Lists internal pages (see Section 6 for details):
+
+1. **Configure the widget**:
+   ```bash
+   scriptorium edit widgets/pages/list.txt
+   ```
+
+2. **Add page references**:
+   ```
+   about
+   contact
+   documentation
+   ```
+
+#### Featured Posts widget
+
+Highlights specific posts in a sidebar:
+
+1. **Configure the widget**:
+   ```bash
+   scriptorium edit widgets/featuredposts/list.txt
+   ```
+
+2. **Add post references**:
+   ```
+   001 My Important Post
+   002 Another Featured Post
+   ```
+
+### Adding widgets to your layout
+
+To include widgets in your site:
+
+1. **Edit your layout configuration**:
+   ```bash
+   scriptorium edit config/layout.txt
+   ```
+
+2. **Add widget containers** to your layout:
+   ```
+   header
+   left   20%
+   main
+   right  20%
+   footer
+   ```
+
+3. **Configure the sidebar** to include widgets:
+   ```bash
+   scriptorium edit config/left.txt
+   ```
+
+4. **Add widget references**:
+   ```
+   .widget links
+   .widget pages
+   .widget featuredposts
+   ```
+
+### Creating custom widgets
+
+For advanced customization, you can create your own widgets:
+
+1. **Create a widget directory**:
+   ```bash
+   mkdir -p widgets/my-custom-widget
+   ```
+
+2. **Create the widget configuration**:
+   ```bash
+   scriptorium edit widgets/my-custom-widget/config.txt
+   ```
+
+3. **Create the widget template**:
+   ```bash
+   scriptorium edit widgets/my-custom-widget/template.lt3
+   ```
+
+4. **Register the widget** in your view's configuration
+
+### Widget styling
+
+Widgets inherit styling from your theme, but you can add custom CSS:
+
+1. **Create widget-specific CSS**:
+   ```bash
+   scriptorium edit themes/my-custom-theme/assets/widgets.css
+   ```
+
+2. **Include the CSS** in your layout templates
+
+### Best practices for customization
+
+- **Start small**: Make incremental changes and test frequently
+- **Keep backups**: Save copies of working configurations
+- **Use version control**: Track your customizations with git
+- **Test thoroughly**: Ensure changes work across different content types
+- **Document changes**: Keep notes on what you've customized
+
+### Troubleshooting customizations
+
+Common issues and solutions:
+
+- **Changes not appearing**: Run `scriptorium generate` to rebuild
+- **Broken layout**: Check for syntax errors in templates
+- **Styling issues**: Verify CSS syntax and file paths
+- **Widget not working**: Check widget configuration and file permissions
+
+Customization in Scriptorium strikes a balance between flexibility and simplicity, allowing you to create unique sites while maintaining the core functionality and reliability of the platform. 

data/doc/user_guide_section_8.md

@@ -0,0 +1,224 @@
+# 8. Advanced Features
+
+Scriptorium includes several advanced features that extend its functionality beyond basic blogging. These features help you integrate with external platforms and enhance your site's social presence.
+
+## Reddit Integration
+
+Scriptorium includes built-in Reddit integration that allows you to automatically share your blog posts to Reddit. This feature helps increase your content's visibility and drive traffic to your site.
+
+### Setting up Reddit integration
+
+Before you can use Reddit integration, you need to create a Reddit application and configure your credentials:
+
+1. **Create a Reddit application**:
+   - Go to https://www.reddit.com/prefs/apps
+   - Click "Create App" or "Create Another App"
+   - Choose "script" as the application type
+   - Fill in the required fields (name, description, redirect URI)
+   - Note your client ID and client secret
+
+2. **Configure Reddit credentials**:
+   ```bash
+   scriptorium edit config/reddit.json
+   ```
+
+3. **Add your Reddit credentials** to the configuration file:
+   ```json
+   {
+     "client_id": "your_client_id_here",
+     "client_secret": "your_client_secret_here",
+     "username": "your_reddit_username",
+     "password": "your_reddit_password",
+     "user_agent": "scriptorium-bot/1.0"
+   }
+   ```
+
+4. **Set appropriate permissions** for the configuration file:
+   ```bash
+   chmod 600 config/reddit.json
+   ```
+
+### Using Reddit integration
+
+Once configured, you can automatically post to Reddit when you publish blog posts:
+
+1. **Add Reddit metadata** to your blog posts:
+   ```
+   .title My Blog Post Title
+   .reddit_subreddit programming
+   .reddit_title My Blog Post Title
+   .reddit_flair "Discussion"
+   ```
+
+2. **Available Reddit metadata**:
+   - `.reddit_subreddit`: Target subreddit (e.g., "programming", "webdev")
+   - `.reddit_title`: Custom title for Reddit (optional, uses post title if not specified)
+   - `.reddit_flair`: Post flair (optional)
+   - `.reddit_nsfw`: Mark as NSFW (true/false)
+   - `.reddit_spoiler`: Mark as spoiler (true/false)
+
+3. **Publish your post**:
+   ```bash
+   scriptorium publish 001
+   ```
+
+4. **The post will automatically be shared** to Reddit with the specified metadata
+
+### Reddit integration best practices
+
+- **Choose appropriate subreddits**: Target subreddits relevant to your content
+- **Follow subreddit rules**: Ensure your content complies with each subreddit's guidelines
+- **Use descriptive titles**: Make your Reddit titles compelling and accurate
+- **Engage with comments**: Respond to comments on your Reddit posts
+- **Don't spam**: Avoid posting too frequently to the same subreddits
+- **Respect rate limits**: Reddit has API rate limits, so don't post too many times in quick succession
+
+### Troubleshooting Reddit integration
+
+Common issues and solutions:
+
+- **Authentication errors**: Verify your credentials in `config/reddit.json`
+- **Rate limiting**: Wait before posting again if you hit rate limits
+- **Subreddit not found**: Check that the subreddit name is correct and exists
+- **Permission denied**: Ensure your Reddit account has permission to post to the target subreddit
+
+## Social Media Features
+
+Scriptorium includes several features to enhance your social media presence and make your content more shareable.
+
+### Social media metadata
+
+Add social media metadata to your posts to improve how they appear when shared:
+
+```
+.title My Blog Post Title
+.og_title My Blog Post Title
+.og_description A compelling description of my blog post
+.og_image /assets/my-featured-image.jpg
+.twitter_card summary_large_image
+.twitter_title My Blog Post Title
+.twitter_description A compelling description for Twitter
+.twitter_image /assets/my-featured-image.jpg
+```
+
+### Open Graph tags
+
+Open Graph tags control how your content appears when shared on Facebook, LinkedIn, and other platforms:
+
+- **`.og_title`**: Title for social media shares
+- **`.og_description`**: Description for social media shares
+- **`.og_image`**: Featured image for social media shares
+- **`.og_type`**: Content type (article, website, etc.)
+- **`.og_url`**: Canonical URL for the content
+
+### Twitter Card tags
+
+Twitter Card tags optimize your content for Twitter sharing:
+
+- **`.twitter_card`**: Card type (summary, summary_large_image, app, player)
+- **`.twitter_title`**: Title for Twitter shares
+- **`.twitter_description`**: Description for Twitter shares
+- **`.twitter_image`**: Image for Twitter shares
+- **`.twitter_site`**: Your Twitter username
+- **`.twitter_creator`**: Content creator's Twitter username
+
+### Social sharing buttons
+
+Add social sharing buttons to your posts:
+
+1. **Configure social sharing** in your theme:
+   ```bash
+   scriptorium edit themes/my-theme/templates/post.lt3
+   ```
+
+2. **Add sharing buttons** to your post template:
+   ```html
+   <div class="social-share">
+     <a href="https://twitter.com/intent/tweet?url=%{post.url}&text=%{post.title}" target="_blank">Share on Twitter</a>
+     <a href="https://www.facebook.com/sharer/sharer.php?u=%{post.url}" target="_blank">Share on Facebook</a>
+     <a href="https://www.linkedin.com/sharing/share-offsite/?url=%{post.url}" target="_blank">Share on LinkedIn</a>
+   </div>
+   ```
+
+### RSS feeds
+
+Scriptorium automatically generates RSS feeds for your content:
+
+- **Main RSS feed**: `your-site.com/feed.xml`
+- **Category-specific feeds**: `your-site.com/category/feed.xml`
+- **Tag-specific feeds**: `your-site.com/tag/feed.xml`
+
+### Email subscriptions
+
+Set up email subscriptions for your blog:
+
+1. **Configure email settings**:
+   ```bash
+   scriptorium edit config/email.txt
+   ```
+
+2. **Add subscription form** to your site:
+   ```html
+   <form action="/subscribe" method="post">
+     <input type="email" name="email" placeholder="Enter your email">
+     <button type="submit">Subscribe</button>
+   </form>
+   ```
+
+### Analytics integration
+
+Track your site's performance with analytics:
+
+1. **Google Analytics**:
+   ```bash
+   scriptorium edit config/analytics.txt
+   ```
+   
+   Add your Google Analytics tracking code:
+   ```
+   GA_TRACKING_ID: UA-XXXXXXXXX-X
+   ```
+
+2. **Other analytics services**:
+   - Add tracking codes to your theme's header template
+   - Configure privacy settings and cookie consent
+   - Set up conversion tracking
+
+### Social media automation
+
+Automate your social media presence:
+
+1. **Scheduled posting**: Set up automated posting to social platforms
+2. **Cross-platform sharing**: Share content across multiple platforms simultaneously
+3. **Content recycling**: Automatically reshare older content
+4. **Engagement tracking**: Monitor likes, shares, and comments
+
+### Best practices for social media
+
+- **Consistent branding**: Use consistent colors, fonts, and imagery across platforms
+- **Engage with your audience**: Respond to comments and messages
+- **Post regularly**: Maintain a consistent posting schedule
+- **Use hashtags strategically**: Research and use relevant hashtags
+- **Monitor performance**: Track which content performs best
+- **Optimize for each platform**: Tailor content for different social media platforms
+
+### Privacy and security considerations
+
+When using social media features:
+
+- **Protect personal information**: Be careful with personal data in social media metadata
+- **Use HTTPS**: Ensure your site uses HTTPS for secure sharing
+- **Respect user privacy**: Implement appropriate privacy policies
+- **Secure API keys**: Keep social media API keys and credentials secure
+- **Monitor for abuse**: Watch for spam or inappropriate use of your social features
+
+### Troubleshooting social media features
+
+Common issues and solutions:
+
+- **Images not appearing**: Check image paths and ensure images are publicly accessible
+- **Metadata not updating**: Clear social media cache or use debugging tools
+- **Sharing buttons not working**: Verify JavaScript is enabled and URLs are correct
+- **Analytics not tracking**: Check tracking code installation and ad blockers
+
+Advanced features in Scriptorium help you extend your reach beyond your blog and engage with audiences across multiple platforms. These features are designed to work seamlessly with your existing content while providing powerful tools for social media management and audience growth.