jackdaw 1.0.0 → 1.0.1

data/usejackdaw.com.site/site/src/content.page.md

@@ -0,0 +1,300 @@
+# Content Guide
+
+Everything you need to know about creating content in Jackdaw.
+
+## Content Files
+
+Content is written in Markdown in `site/src/`.
+
+### File Naming Convention
+
+```
+[date-]name.type.md
+```
+
+**Examples:**
+- `index.page.md` → `/index.html` (homepage)
+- `about.page.md` → `/about.html` (page)
+- `2026-01-06-hello.blog.md` → `/2026-01-06-hello.html` (blog post)
+- `docs/guide.page.md` → `/docs/guide.html` (nested)
+
+### Content Types
+
+The `.type.` part determines template and behavior:
+
+- **page** - Static pages (no date required)
+- **blog** - Blog posts (dated)
+- **post** - Alternative to blog
+- **article** - Alternative to blog
+- **Custom** - Create your own types
+
+## Title Extraction
+
+Jackdaw extracts titles from:
+category: Tutorial
+featured: true
+image: /images/hero.jpg
+---
+```
+
+Access in templates:
+```erb
+<% if featured %>
+  <span class="badge">Featured</span>
+<% end %>
+```
+
+## Writing Markdown
+
+Jackdaw uses GitHub-flavored Markdown via Kramdown.
+
+### Headings
+
+```markdown
+# Heading 1
+## Heading 2
+### Heading 3
+```
+
+### Text Formatting
+
+```markdown
+**bold** or __bold__
+*italic* or _italic_
+~~strikethrough~~
+`code`
+```
+
+### Links
+
+```markdown
+[Link text](https://example.com)
+[Relative link](/about.html)
+[Link with title](https://example.com "Title")
+```
+
+### Images
+
+```markdown
+![Alt text](/images/photo.jpg)
+![With title](/images/photo.jpg "Photo title")
+```
+
+### Lists
+
+```markdown
+- Unordered item
+- Another item
+  - Nested item
+
+1. Ordered item
+2. Another item
+   1. Nested ordered
+```
+
+### Code Blocks
+
+With syntax highlighting:
+
+````markdown
+```ruby
+def hello
+  puts "Hello, world!"
+end
+```
+````
+
+Supported languages: Ruby, JavaScript, Python, HTML, CSS, Shell, and 200+ more.
+
+### Blockquotes
+
+```markdown
+> This is a quote
+> spanning multiple lines
+```
+
+### Tables
+
+```markdown
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+| Cell 3   | Cell 4   |
+```
+
+### Horizontal Rules
+
+```markdown
+---
+```
+
+### HTML
+
+You can include HTML:
+
+```markdown
+<div class="custom">
+  Regular markdown **works** here too.
+</div>
+```
+
+## Automatic Excerpt
+
+The first paragraph becomes the excerpt:
+
+```markdown
+---
+title: My Post
+---
+
+This paragraph is automatically used as the excerpt.
+
+This is regular content.
+```
+
+Or set it manually:
+
+```markdown
+---
+title: My Post
+excerpt: Custom excerpt here
+---
+
+Content...
+```
+
+## Nested Content
+
+Organize with directories:
+
+```
+site/src/
+├── index.page.md
+├── about.page.md
+├── blog/
+│   ├── 2026-01-01-first.blog.md
+│   └── 2026-01-02-second.blog.md
+└── docs/
+    ├── getting-started.page.md
+    └── api.page.md
+```
+
+URLs match structure:
+- `blog/2026-01-01-first.blog.md` → `/blog/2026-01-01-first.html`
+- `docs/api.page.md` → `/docs/api.html`
+
+## Dates
+
+### Automatic Date Extraction
+
+Jackdaw extracts dates from filenames:
+
+```
+2026-01-06-post-name.blog.md
+^         ^
+Date      │
+          Title
+```
+
+Formats:
+- `YYYY-MM-DD-title.type.md`
+- `YYYY-MM-title.type.md`  
+- `YYYY-title.type.md`
+
+### No Date
+
+For pages that don't need dates:
+
+```
+about.page.md  # No date in filename
+```
+
+## Title Extraction
+
+Jackdaw extracts titles from:
+
+1. **First H1** in content (highest priority):
+   ```markdown
+   # This Becomes the Title
+   ```
+
+2. **Filename** (fallback):
+   ```
+   my-awesome-post.blog.md
+   → "My Awesome Post"
+   ```
+
+## Content Organization Patterns
+
+### Blog
+
+```
+site/src/
+├── index.page.md                    # Blog homepage
+└── blog/
+    ├── 2026-01-01-hello.blog.md
+    ├── 2026-01-02-second.blog.md
+    └── 2026-01-03-third.blog.md
+```
+
+### Documentation Site
+
+```
+site/src/
+├── index.page.md                    # Docs homepage
+├── getting-started.page.md
+├── installation.page.md
+└── guides/
+    ├── basics.page.md
+    ├── advanced.page.md
+    └── api.page.md
+```
+
+### Marketing Site
+
+```
+site/src/
+├── index.page.md                    # Homepage
+├── about.page.md
+├── pricing.page.md
+├── contact.page.md
+└── blog/
+    └── 2026-01-01-announcement.blog.md
+```
+
+## RSS/Atom Feeds
+
+Feeds are automatically generated for blog content:
+
+- `public/feed.xml` (RSS 2.0)
+- `public/atom.xml` (Atom 1.0)
+
+Includes:
+- 20 most recent posts
+- Title, link, date
+- Excerpt/description
+
+## Sitemap
+
+`public/sitemap.xml` is automatically generated with:
+
+- All pages and posts
+- Correct priorities (1.0 for index, 0.8 for pages, 0.6 for posts)
+- Change frequency hints
+- Last modification dates
+
+## Best Practices
+
+1. **Use descriptive filenames** - They become URLs
+2. **Add excerpts** - First paragraph is used as excerpt
+3. **Organize with directories** - Keep related content together
+4. **Include dates for time-sensitive content**
+5. **Write semantic Markdown** - Use proper headings hierarchy
+6. **Add alt text to images** - For accessibility
+
+## Tips
+
+- **Test locally** - Use `jackdaw serve` to preview
+- **Incremental builds** - Only changed files rebuild
+- **Link relatively** - Use `/about.html` not `https://...`
+- **Check output** - Look in `public/` to verify

data/usejackdaw.com.site/site/src/deployment.page.md

@@ -0,0 +1,306 @@
+# Deployment
+
+Deploy your static site to any hosting platform.
+
+## Build for Production
+
+```bash
+jackdaw build --clean
+```
+
+This creates a `public/` directory with your complete site.
+
+## Static Hosts
+
+### Netlify
+
+**1. Install Netlify CLI:**
+```bash
+npm install -g netlify-cli
+```
+
+**2. Deploy:**
+```bash
+cd public
+netlify deploy --prod
+```
+
+Or connect your Git repository for automatic deployments.
+
+**netlify.toml:**
+```toml
+[build]
+  command = "gem install jackdaw && jackdaw build"
+  publish = "public"
+
+[build.environment]
+  RUBY_VERSION = "4.0.0"
+```
+
+### Vercel
+
+**1. Install Vercel CLI:**
+```bash
+npm install -g vercel
+```
+
+**2. Deploy:**
+```bash
+vercel --prod
+```
+
+**vercel.json:**
+```json
+{
+  "buildCommand": "gem install jackdaw && jackdaw build",
+  "outputDirectory": "public"
+}
+```
+
+### GitHub Pages
+
+**1. Build locally:**
+```bash
+jackdaw build
+```
+
+**2. Push to gh-pages branch:**
+```bash
+cd public
+git init
+git add .
+git commit -m "Deploy"
+git remote add origin https://github.com/username/repo.git
+git push -f origin master:gh-pages
+```
+
+Or use GitHub Actions:
+
+**.github/workflows/deploy.yml:**
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 4.0
+      
+      - run: gem install jackdaw
+      - run: jackdaw build
+      
+      - uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public
+```
+
+### Cloudflare Pages
+
+Connect your Git repository and configure:
+
+- **Build command:** `gem install jackdaw && jackdaw build`
+- **Build output directory:** `public`
+- **Environment variables:**
+  - `RUBY_VERSION = 4.0.0`
+
+### AWS S3 + CloudFront
+
+**1. Build:**
+```bash
+jackdaw build
+```
+
+**2. Upload to S3:**
+```bash
+aws s3 sync public/ s3://your-bucket/ --delete
+```
+
+**3. Invalidate CloudFront cache:**
+```bash
+aws cloudfront create-invalidation \
+  --distribution-id YOUR_ID \
+  --paths "/*"
+```
+
+### Simple Server
+
+Any web server that serves static files:
+
+**nginx:**
+```nginx
+server {
+  listen 80;
+  server_name example.com;
+  root /var/www/public;
+  
+  location / {
+    try_files $uri $uri/ =404;
+  }
+}
+```
+
+**Apache:**
+```apache
+<VirtualHost *:80>
+  ServerName example.com
+  DocumentRoot /var/www/public
+  
+  <Directory /var/www/public>
+    Options -Indexes +FollowSymLinks
+    AllowOverride All
+    Require all granted
+  </Directory>
+</VirtualHost>
+```
+
+## Custom Domain
+
+### DNS Configuration
+
+Point your domain to your host:
+
+**Netlify/Vercel:**
+- Add CNAME record: `www` → `your-site.netlify.app`
+- Or use their nameservers
+
+**CloudFlare Pages:**
+- Add CNAME: `www` → `your-site.pages.dev`
+
+**GitHub Pages:**
+- Add CNAME file in `public/` with your domain
+- Add A records:
+  ```
+  185.199.108.153
+  185.199.109.153
+  185.199.110.153
+  185.199.111.153
+  ```
+
+## SSL/HTTPS
+
+All modern hosts provide free SSL:
+
+- **Netlify** - Automatic with Let's Encrypt
+- **Vercel** - Automatic
+- **CloudFlare** - Automatic
+- **GitHub Pages** - Automatic for custom domains
+
+## Optimization Tips
+
+### Before Deploy
+
+```bash
+# Clean build
+jackdaw build --clean
+
+# Minify CSS (optional)
+npx cssnano public/css/*.css
+
+# Optimize images
+npx imagemin public/images/* --out-dir=public/images
+```
+
+### Performance
+
+1. **Use a CDN** - Most hosts provide this
+2. **Enable compression** - Gzip/Brotli
+3. **Set cache headers** - Long TTL for assets
+4. **Optimize images** - WebP, proper sizing
+5. **Minify assets** - CSS, JS
+
+### SEO
+
+1. **Sitemap** - Automatically generated at `/sitemap.xml`
+2. **RSS feeds** - Automatically at `/feed.xml` and `/atom.xml`
+3. **SEO tags** - Use `<%= seo_tags %>` in templates
+4. **Canonical URLs** - Use `<%= canonical_tag %>`
+5. **Submit to search engines** - Google Search Console
+
+## Continuous Deployment
+
+### With Git
+
+1. Push code to GitHub/GitLab
+2. Host connects to repository
+3. Automatic builds on push
+4. Site updates automatically
+
+### Build Command
+
+Most hosts need:
+
+```bash
+gem install jackdaw && jackdaw build
+```
+
+### Build Time
+
+Jackdaw is fast:
+- Small site (10 pages): ~0.1s
+- Medium site (100 pages): ~0.5s  
+- Large site (600 pages): ~0.9s
+
+## Rollback
+
+If something breaks:
+
+**Netlify:**
+```bash
+netlify rollback
+```
+
+**Vercel:**
+- Use dashboard to rollback deployment
+
+**Git-based:**
+```bash
+git revert HEAD
+git push
+```
+
+## Monitoring
+
+Check your deployed site:
+
+```bash
+# Status
+curl -I https://example.com
+
+# Performance
+curl -w "@curl-format.txt" -o /dev/null -s https://example.com
+```
+
+**curl-format.txt:**
+```
+time_total: %{time_total}s
+```
+
+## Troubleshooting
+
+**Build fails:**
+- Check Ruby version (need 4.0+)
+- Install bundler if using Gemfile
+- Check build logs for errors
+
+**404 errors:**
+- Verify public/ has files
+- Check deployment directory setting
+- Ensure build completed successfully
+
+**Assets not loading:**
+- Use absolute paths: `/css/style.css`
+- Check asset file locations
+- Verify asset directory deployed
+
+**Slow build:**
+- Use incremental builds (default)
+- Cache dependencies
+- Check build machine specs