abqari 1.1.0

data/lib/abqari/templates/site_skeleton/bin/fetch-folio

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Force-refresh the Folio cache. Build does this automatically — this script
+# exists for cases where you want to refresh without a full rebuild (e.g. you
+# just published a new book and want to verify the cache picks it up).
+#
+# Usage: bin/fetch-folio
+
+ENV['ABQARI_SITE_ROOT'] ||= File.expand_path('..', __dir__)
+# Resolve the bundle from this site, not from cwd — `bundler/setup`
+# finds its Gemfile relative to the current directory, so running this
+# from elsewhere would load an unrelated bundle (or none) and fail.
+ENV['BUNDLE_GEMFILE']   ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+require 'abqari'
+
+Abqari.run_cli do
+  site  = Abqari::Site.new
+  folio = Abqari::Folio.new(site)
+
+  unless folio.enabled?
+    warn 'Folio: not configured. Set folio.base_url and folio.author_slug in config/site.yml.'
+    exit 1
+  end
+
+  # Drop ETags so we get a fresh 200 even if Folio thinks nothing changed.
+  Dir.glob(File.join(folio.cache_dir, 'etag-*')).each { |f| File.delete(f) }
+
+  folio.fetch
+end

data/lib/abqari/templates/site_skeleton/bin/fetch-fonts

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Self-host fonts declared in config/site.yml. Downloads woff2 files from
+# Google Fonts and writes a fonts.css with rewritten URLs into vendor/fonts/.
+# Run once after adding/changing the `fonts:` block. Build copies the result
+# into _site/assets/fonts/.
+
+ENV['ABQARI_SITE_ROOT'] ||= File.expand_path('..', __dir__)
+# Resolve the bundle from this site, not from cwd — `bundler/setup`
+# finds its Gemfile relative to the current directory, so running this
+# from elsewhere would load an unrelated bundle (or none) and fail.
+ENV['BUNDLE_GEMFILE']   ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+require 'abqari'
+
+Abqari.run_cli do
+  Abqari::FontPipeline.new(Abqari::Site.new).fetch
+end

data/lib/abqari/templates/site_skeleton/bin/import

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Content importer — pulls content from another platform's export
+# into this site's content/<collection>/ directory.
+#
+# Usage:
+#   bin/import substack ~/Downloads/substack-export.zip
+#   bin/import ghost ~/Downloads/export.json --into notes
+#   bin/import jekyll ~/old-site/ --dry-run
+#
+# Run `bin/import --help` for the full list of platforms and flags.
+# The script writes a markdown report to `_import_report.md` (gitignored)
+# summarising what was imported, skipped, and warned about.
+
+ENV['ABQARI_ENV']       ||= 'development'
+ENV['ABQARI_SITE_ROOT'] ||= File.expand_path('..', __dir__)
+# Resolve the bundle from this site, not from cwd — `bundler/setup`
+# finds its Gemfile relative to the current directory, so running this
+# from elsewhere would load an unrelated bundle (or none) and fail.
+ENV['BUNDLE_GEMFILE']   ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+require 'abqari'
+require 'abqari/importers'
+require 'abqari/importers/cli'
+
+Abqari.run_cli do
+  ok = Abqari::Importers::CLI.run(ARGV, site_root: ENV['ABQARI_SITE_ROOT'])
+  exit(ok ? 0 : 1)
+end

data/lib/abqari/templates/site_skeleton/bin/index

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Build the Pagefind search index for _site/. Standalone wrapper; bin/build
+# also runs this automatically when `search: true` is set in config/site.yml,
+# so you'd typically only call this directly to re-index without a full build.
+#
+# Requires pagefind on PATH. Install:
+#   macOS:   brew install pagefind
+#   General: curl -LSf https://pagefind.app/install.sh | bash
+#   Cargo:   cargo install pagefind
+
+ENV['ABQARI_ENV']       ||= 'production'
+ENV['ABQARI_SITE_ROOT'] ||= File.expand_path('..', __dir__)
+# Resolve the bundle from this site, not from cwd — `bundler/setup`
+# finds its Gemfile relative to the current directory, so running this
+# from elsewhere would load an unrelated bundle (or none) and fail.
+ENV['BUNDLE_GEMFILE']   ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+require 'abqari'
+
+Abqari.run_cli do
+  site = Abqari::Site.new
+  unless Dir.exist?(site.output_dir) && !Dir.empty?(site.output_dir)
+    abort '_site/ is empty or missing — run `bin/build` first.'
+  end
+
+  Abqari::Search.new(site).run!
+end

data/lib/abqari/templates/site_skeleton/bin/new

@@ -0,0 +1,235 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Multi-purpose generator for an Abqari site.
+#
+# Usage:
+#   bin/new                          Configure the site (interactive form via flags)
+#     --name "My Blog"               Set title and author (required for site config)
+#     --description "..."            Set description
+#     --locale fr                    ISO 639-1 locale (default: en)
+#     --theme bootstrap              Theme (default: minimal)
+#     --clean                        Wipe example posts, audit/, vendor/fonts, git history
+#
+#   bin/new post "Title"             Scaffold a new post bundle:
+#                                      content/posts/<YYYY-MM-DD>-<slug>/index.md
+#
+#   bin/new page "Title"             Scaffold a top-level page:
+#                                      content/<slug>.md
+#
+# Run site config once after `git clone`. Use `post` and `page` whenever you're
+# adding new content; both print the path of the file they created.
+
+require 'optparse'
+require 'fileutils'
+require 'time'
+
+VALID_THEMES = %w[minimal magazine notebook sand bootstrap custom none].freeze
+ROOT = File.expand_path('..', __dir__)
+
+# --- Shared helpers --------------------------------------------------------
+
+def slugify(text)
+  text.to_s.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/\A-|-\z/, '')
+end
+
+# --- Subcommand: bin/new post "Title" --------------------------------------
+
+def create_post(title)
+  slug = slugify(title)
+  abort('Provide a non-empty title') if slug.empty?
+
+  date = Time.now.strftime('%Y-%m-%d')
+  bundle_dir = File.join(ROOT, 'content', 'posts', "#{date}-#{slug}")
+  index_path = File.join(bundle_dir, 'index.md')
+
+  if Dir.exist?(bundle_dir)
+    abort("Post already exists at content/posts/#{date}-#{slug}/")
+  end
+
+  FileUtils.mkdir_p(bundle_dir)
+  File.write(index_path, <<~MD)
+    ---
+    title: #{title}
+    published: true                # flip to `false` to keep this a draft —
+                                   #   stays out of production builds but
+                                   #   renders in `bin/serve` with a banner.
+    date: #{date}
+    description:
+    tags: []
+    # image: hero.jpg              # optional bundle hero — drop hero.jpg
+    #                              #   alongside this index.md and uncomment
+    # share_image:                 # optional explicit OG image override
+    ---
+
+    Write your post here.
+
+    Reference colocated images by relative name (`![alt](hero.jpg)`) —
+    the build's image pipeline rewrites them into responsive `<picture>`
+    blocks with AVIF + WebP + optimised fallback variants automatically.
+  MD
+
+  puts "✓ Created content/posts/#{date}-#{slug}/index.md"
+  puts ''
+  puts 'Next:'
+  puts '  - Drop colocated images alongside index.md (they go through the image pipeline).'
+  puts '  - bin/serve to preview locally.'
+  puts '  - Set `published: false` while drafting; it stays out of production builds.'
+end
+
+# --- Subcommand: bin/new page "Title" --------------------------------------
+
+def create_page(title)
+  slug = slugify(title)
+  abort('Provide a non-empty title') if slug.empty?
+
+  rel_path = "content/#{slug}.md"
+  abs_path = File.join(ROOT, rel_path)
+
+  if File.exist?(abs_path)
+    abort("Page already exists at #{rel_path}")
+  end
+
+  File.write(abs_path, <<~MD)
+    ---
+    title: #{title}
+    published: true                # flip to `false` to keep this a draft —
+                                   #   stays out of production builds but
+                                   #   renders in `bin/serve` with a banner.
+    description:
+    nav:
+      order: 99
+    ---
+
+    # #{title}
+
+    Write your page content here.
+  MD
+
+  puts "✓ Created #{rel_path}"
+  puts ''
+  puts "It will appear in the nav at order 99 (last) by default — adjust the `nav.order`"
+  puts "value in the front matter to position it. Set `nav: ~` (or remove the block) to"
+  puts 'keep it out of the nav entirely.'
+end
+
+# --- Subcommand: bin/new (no args) — site configuration --------------------
+
+def configure_site(options)
+  abort('--name is required (run `bin/new --help`)') unless options[:name]
+
+  unless VALID_THEMES.include?(options[:theme])
+    abort("Unknown theme: #{options[:theme]}. Valid: #{VALID_THEMES.join(', ')}")
+  end
+
+  config_path = File.join(ROOT, 'config', 'site.yml')
+  abort("config/site.yml not found at #{config_path}") unless File.exist?(config_path)
+
+  config = File.read(config_path, encoding: 'UTF-8')
+  config = replace_or_insert(config, 'title',       quote_yaml(options[:name]))
+  config = replace_or_insert(config, 'author',      quote_yaml(options[:name]))
+  config = replace_or_insert(config, 'description', quote_yaml(options[:description])) if options[:description]
+  config = replace_or_insert(config, 'locale',      options[:locale])
+  config = replace_or_insert(config, 'theme',       options[:theme])
+
+  File.write(config_path, config)
+  puts '✓ Updated config/site.yml'
+
+  clean_site if options[:clean]
+
+  puts ''
+  puts "Site configured: #{options[:name]} (locale: #{options[:locale]}, theme: #{options[:theme]})"
+  puts ''
+  puts 'Next steps:'
+  puts '  bundle install      # if not yet installed'
+  puts '  bin/new post "..."  # scaffold a new post bundle'
+  puts '  bin/serve           # start the dev server on http://localhost:4000'
+  puts ''
+  puts 'When ready, edit config/site.yml to set environments.production.url to your real domain.'
+end
+
+def clean_site
+  posts_dir = File.join(ROOT, 'content', 'posts')
+  if Dir.exist?(posts_dir)
+    Dir.glob(File.join(posts_dir, '*')).each { |entry| FileUtils.rm_rf(entry) if File.directory?(entry) }
+    puts '✓ Removed example posts'
+  end
+
+  audit_dir = File.join(ROOT, 'audit')
+  if Dir.exist?(audit_dir)
+    Dir.glob(File.join(audit_dir, '*.md')).each { |f| File.delete(f) }
+    puts '✓ Cleared audit/'
+  end
+
+  fonts_dir = File.join(ROOT, 'vendor', 'fonts')
+  if Dir.exist?(fonts_dir)
+    Dir.glob(File.join(fonts_dir, '*')).each { |f| File.delete(f) if File.file?(f) }
+    puts '✓ Cleared vendor/fonts/'
+  end
+
+  site_dir = File.join(ROOT, '_site')
+  if Dir.exist?(site_dir)
+    FileUtils.rm_rf(site_dir)
+    puts '✓ Removed _site/'
+  end
+
+  git_dir = File.join(ROOT, '.git')
+  if Dir.exist?(git_dir)
+    FileUtils.rm_rf(git_dir)
+    Dir.chdir(ROOT) do
+      system('git init -b main', out: File::NULL, err: File::NULL)
+    end
+    puts '✓ Re-initialised git on a fresh main branch'
+  end
+end
+
+def replace_or_insert(content, key, value)
+  pattern = /^#{Regexp.escape(key)}:\s*.*$/
+  if content.match?(pattern)
+    content.sub(pattern, "#{key}: #{value}")
+  else
+    "#{content.chomp}\n#{key}: #{value}\n"
+  end
+end
+
+def quote_yaml(value)
+  return value unless value.match?(/[:#&*\[\]{}|>]|^\s|\s$/)
+
+  "\"#{value.gsub('"', '\\"')}\""
+end
+
+# --- Dispatcher ------------------------------------------------------------
+
+case ARGV.first
+when 'post'
+  ARGV.shift
+  abort('Usage: bin/new post "Title"') if ARGV.empty?
+  create_post(ARGV.join(' '))
+when 'page'
+  ARGV.shift
+  abort('Usage: bin/new page "Title"') if ARGV.empty?
+  create_page(ARGV.join(' '))
+else
+  options = { locale: 'en', theme: 'minimal', clean: false }
+
+  OptionParser.new do |opts|
+    opts.banner = 'Usage: bin/new [post|page] "Title"   OR   bin/new --name NAME [options]'
+    opts.separator ''
+    opts.separator 'Subcommands:'
+    opts.separator '    post "Title"                 Scaffold a new post bundle'
+    opts.separator '    page "Title"                 Scaffold a top-level page'
+    opts.separator ''
+    opts.separator 'Site configuration options (no subcommand):'
+    opts.on('--name NAME', 'Site title (required)') { |v| options[:name] = v }
+    opts.on('--description TEXT', 'Site description (used in <meta>, OG, RSS)') { |v| options[:description] = v }
+    opts.on('--locale CODE', 'ISO 639-1 locale (en, es, fr, de, …) [default: en]') { |v| options[:locale] = v }
+    opts.on('--theme NAME', "Theme: #{VALID_THEMES.join(', ')} [default: minimal]") { |v| options[:theme] = v }
+    opts.on('--clean', 'Remove example posts, audit reports, and reset git history') { options[:clean] = true }
+    opts.on('-h', '--help', 'Show this message') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  configure_site(options)
+end

data/lib/abqari/templates/site_skeleton/bin/serve

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Dev server with file-watcher + SSE live reload. Builds the site,
+# starts WEBrick on localhost:4000, watches content/, config/, data/,
+# app/ for changes and incrementally rebuilds.
+#
+# Takes no arguments on purpose. Both knobs are environment variables:
+#   ABQARI_PORT=4001    — when 4000 is taken by another site's dev server
+#   ABQARI_BIND=0.0.0.0 — to preview on a phone over LAN
+
+ENV['ABQARI_ENV']       ||= 'development'
+ENV['ABQARI_SITE_ROOT'] ||= File.expand_path('..', __dir__)
+# Resolve the bundle from this site, not from cwd — `bundler/setup`
+# finds its Gemfile relative to the current directory, so running this
+# from elsewhere would load an unrelated bundle (or none) and fail.
+ENV['BUNDLE_GEMFILE']   ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'
+require 'abqari'
+
+Abqari.run_cli do
+  # Check ABQARI_PORT before the build — a typo shouldn't cost a full
+  # site build before you're told about it.
+  Abqari::Server.validate_env!
+
+  site = Abqari::Site.new
+  site.build
+  Abqari::Server.new(site).start
+end

data/lib/abqari/templates/site_skeleton/config/site.blank.yml.tt

@@ -0,0 +1,65 @@
+# Abqari site configuration.
+# See the engine's reference config (or run `abqari new <other>` without
+# --blank) for the full surface with documentation.
+
+title: <%= yaml.call(title) %>
+description: <%= yaml.call(description) %>
+author: <%= yaml.call(author) %>
+locale: <%= yaml.call(locale) %>
+theme: <%= yaml.call(theme) %>
+<%= fonts_block_blank %>
+collections:
+  posts:
+    enabled: true
+    index:
+      cover: photo
+      show_date: true
+      show_description: true
+      description_truncate: 160
+      show_reading_time: true
+      show_tags: false
+      latest_count: 8
+    show:
+      cover: photo
+      toc:
+        enabled: true
+        min_headings: 3
+        levels: [2, 3]
+      next:
+        enabled: true
+      related:
+        enabled: true
+        limit: 3
+        match_by: tags
+        show_image: true
+    archive:
+      enabled: false
+    feeds:
+      enabled: true
+
+  photos:
+    enabled: <%= with.include?('photos') %>
+  publications:
+    enabled: <%= with.include?('publications') %>
+  workshops:
+    enabled: <%= with.include?('workshops') %>
+
+home:
+  latest_post:          false
+  random_post:          false
+  featured_publication: false
+  latest_publication:   false
+  next_workshop:        false
+  latest_photo:         false
+  random_photo:         false
+  photo_gallery:        false
+  contact:              false
+
+footer:
+  signature: "Built with Abqari · {year}"   # {year} is substituted at build time
+
+environments:
+  development:
+    url: http://localhost:4000
+  production:
+    url: https://www.example.com