jekyll-obsidian-site 0.2.0

data/website/lib/jekyll_obsidian/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module JekyllObsidian
+  VERSION = "0.2.0"
+  GEM_NAME = "jekyll-obsidian-site"
+end

data/website/lib/jekyll_obsidian/workspace_layout.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module JekyllObsidian
+  class WorkspaceLayout
+    class Invalid < StandardError; end
+
+    DEFAULT_SOURCE = Object.new.freeze
+    CONTEXT_KEY = "_jekyll_obsidian_runtime"
+    CACHE_DIRECTORY = ".jekyll-obsidian-cache"
+
+    attr_reader :workspace_root, :site_root, :source_root, :source,
+      :destination_root, :jekyll_cache_root, :application_cache_root, :application_assets_root
+
+    def self.resolve(site:, source: DEFAULT_SOURCE)
+      new(site:, source:).tap(&:validate!)
+    end
+
+    def self.relative_source(raw)
+      raise Invalid, "website.source must be a repository-relative directory" unless raw.is_a?(String)
+
+      source = raw.unicode_normalize(:nfc).tr("\\", "/")
+      invalid = source.empty? || source == "." || source.match?(/[[:cntrl:]]/) ||
+        source.match?(/\A[A-Za-z]:\//) || Pathname.new(source).absolute? ||
+        Pathname.new(source).cleanpath.to_s != source ||
+        source.split("/").any? { |part| part.empty? || part == "." || part == ".." }
+      raise Invalid, "website.source must be a normalized repository-relative directory" if invalid
+      if source == CACHE_DIRECTORY || source.start_with?("#{CACHE_DIRECTORY}/")
+        raise Invalid, "website.source must not overlap the application cache"
+      end
+
+      source
+    rescue ArgumentError => exception
+      raise Invalid, "invalid website.source: #{exception.message}"
+    end
+
+    def self.assert_path!(root, target, label, missing: false)
+      relative = Pathname.new(target).relative_path_from(Pathname.new(root))
+      raise Invalid, "#{label} escapes its allowed root" if relative.each_filename.any? { |part| part == ".." }
+
+      cursor = root
+      ([root] + relative.each_filename.map { |part| cursor = File.join(cursor, part) }).each do |path|
+        stat = File.lstat(path)
+        raise Invalid, "#{label} path contains a symbolic link: #{path}" if stat.symlink?
+      rescue Errno::ENOENT
+        break if missing
+        raise Invalid, "#{label} does not exist: #{path}"
+      end
+    rescue ArgumentError
+      raise Invalid, "#{label} escapes its allowed root"
+    end
+
+    def initialize(site:, source:)
+      context = site.config.fetch(CONTEXT_KEY)
+      @workspace_root = File.realpath(context.fetch("workspace_root"))
+      @site_root = File.expand_path(site.source)
+      @source = self.class.relative_source(source.equal?(DEFAULT_SOURCE) ? "docs" : source)
+      @source_root = File.expand_path(@source, @workspace_root)
+      @destination_root = File.expand_path(site.dest)
+      @jekyll_cache_root = File.expand_path(site.cache_dir)
+      @application_cache_root = File.join(@workspace_root, CACHE_DIRECTORY)
+      @application_assets_root = File.expand_path(context.fetch("assets_root"))
+    rescue KeyError => exception
+      raise Invalid, "missing runtime context; use jekyll-obsidian build or dev (#{exception.message})"
+    end
+
+    def validate!
+      self.class.assert_path!(@workspace_root, @application_cache_root, "application cache", missing: true)
+      unless @site_root == File.join(@application_cache_root, "runtime")
+        raise Invalid, "Jekyll source must use the isolated runtime directory"
+      end
+      validate_directory!(@site_root, "Jekyll source", missing: false)
+      self.class.assert_path!(@workspace_root, @source_root, "website.source")
+      raise Invalid, "website.source must be a directory: #{@source}" unless File.directory?(@source_root)
+      unless File.realpath(@source_root) == @source_root
+        raise Invalid, "website.source casing must match the repository path exactly"
+      end
+
+      unless File.dirname(@destination_root) == @application_cache_root &&
+          File.basename(@destination_root).match?(/\Asite(?:-[A-Za-z0-9][A-Za-z0-9._-]*|\-build\.[A-Za-z0-9]+)?\z/)
+        raise Invalid, "destination must be a site directory inside the application cache"
+      end
+      validate_directory!(@destination_root, "destination")
+      unless @jekyll_cache_root == File.join(@site_root, ".jekyll-cache")
+        raise Invalid, "Jekyll cache must use the runtime-local .jekyll-cache directory"
+      end
+      validate_directory!(@jekyll_cache_root, "Jekyll cache")
+      instance_variables.each { |name| instance_variable_get(name).freeze }
+      freeze
+    rescue SystemCallError => exception
+      raise Invalid, "invalid workspace: #{exception.message}"
+    end
+
+    private
+
+    def validate_directory!(path, label, missing: true)
+      self.class.assert_path!(@workspace_root, path, label, missing:)
+      if File.exist?(path) && !File.directory?(path)
+        raise Invalid, "#{label} must be a directory"
+      end
+    end
+  end
+end

data/website/lib/jekyll_obsidian.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "jekyll_obsidian/version"
+require_relative "jekyll_obsidian/value_objects"
+require_relative "jekyll_obsidian/output_text"
+require_relative "jekyll_obsidian/github_markdown"
+require_relative "jekyll_obsidian/url_builder"
+require_relative "jekyll_obsidian/destination_registry"
+require_relative "jekyll_obsidian/media_policy"
+require_relative "jekyll_obsidian/external_media"
+require_relative "jekyll_obsidian/front_matter"
+require_relative "jekyll_obsidian/content_policy"
+require_relative "jekyll_obsidian/directory_indexes"
+require_relative "jekyll_obsidian/raw_html_manifest"
+require_relative "jekyll_obsidian/html_publication"
+require_relative "jekyll_obsidian/ofm_scanner"
+require_relative "jekyll_obsidian/published_markdown"
+require_relative "jekyll_obsidian/site_navigation"
+require_relative "jekyll_obsidian/built_in_themes"
+require_relative "jekyll_obsidian/vault_compiler"
+require_relative "jekyll_obsidian/localized_compiler"
+require_relative "jekyll_obsidian/site_compilation"

data/website/scripts/audit-site.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "find"
+require "json"
+require "pathname"
+require "set"
+require "uri"
+
+require_relative "../lib/jekyll_obsidian/raw_html_manifest"
+
+MAX_BYTES = 1_073_741_824
+EXACT_FILES = %w[
+  index.html 404.html feed.xml sitemap.xml
+  assets/website/catalog.v1.json assets/website/graph.v1.json assets/website/search.v1.json
+  robots.txt site.webmanifest favicon.ico .nojekyll
+].append(JekyllObsidian::RawHtmlManifest::PATH).freeze
+RAW_HTML_MANIFEST = JekyllObsidian::RawHtmlManifest::PATH
+ALLOWED_EXTENSIONS = %w[
+  .html .css .js .mjs .woff .woff2
+  .avif .bmp .gif .jpeg .jpg .png .svg .webp
+  .flac .m4a .mp3 .ogg .wav .webm .3gp
+  .mkv .mov .mp4 .ogv .pdf .canvas .base
+].freeze
+
+def fail_audit(message)
+  warn "site audit: #{message}"
+  exit 1
+end
+
+def generated_markdown_resource?(site_dir, relative)
+  return false unless File.extname(relative).casecmp(".md").zero?
+
+  candidates = ["#{relative.delete_suffix('.md')}/index.html"]
+  if File.basename(relative).casecmp("index.md").zero?
+    directory = File.dirname(relative)
+    candidates << (directory == "." ? "index.html" : "#{directory}/index.html")
+  end
+  candidates.any? { |html| File.file?(File.join(site_dir, html)) }
+end
+
+def raw_html_relative_path(value, label, allow_directory: false)
+  unless value.is_a?(String) && value.valid_encoding? && value.start_with?("/") &&
+      !value.match?(/[?#\\\x00-\x1f\x7f]/) && !value.match?(/%(?:2f|5c)/i)
+    fail_audit("unsafe #{label}: #{value.inspect}")
+  end
+
+  decoded = URI.decode_uri_component(value)
+  segments = decoded.split("/", -1)
+  segments.pop if allow_directory && decoded.end_with?("/")
+  unless decoded.valid_encoding? && segments.first == "" &&
+      segments.drop(1).none? { |segment| segment.empty? || segment == "." || segment == ".." }
+    fail_audit("unsafe #{label}: #{value.inspect}")
+  end
+  decoded.delete_prefix("/")
+rescue ArgumentError
+  fail_audit("unsafe #{label}: #{value.inspect}")
+end
+
+def raw_html_output_files(site_dir)
+  manifest_path = File.join(site_dir, RAW_HTML_MANIFEST)
+  return Set.new unless File.exist?(manifest_path) || File.symlink?(manifest_path)
+
+  stat = File.lstat(manifest_path)
+  fail_audit("raw HTML manifest must be a non-symlink regular file") unless stat.file? && !stat.symlink?
+  payload = JekyllObsidian::RawHtmlManifest.parse(File.read(manifest_path, encoding: "UTF-8"))
+  documents = payload.fetch("documents")
+  files = payload.fetch("files")
+
+  relative_files = files.map { |route| raw_html_relative_path(route, "raw HTML file route") }
+  documents.each do |document|
+    raw_html_relative_path(document.fetch("route"), "raw HTML document route", allow_directory: true)
+    raw_html_relative_path(document.fetch("output"), "raw HTML document output")
+  end
+
+  relative_files.each do |relative|
+    target = File.expand_path(relative, site_dir)
+    inside = target.start_with?("#{site_dir}#{File::SEPARATOR}")
+    unless inside && File.exist?(target) && File.lstat(target).file? && !File.lstat(target).symlink?
+      fail_audit("raw HTML manifest target is missing or unsafe: #{relative}")
+    end
+  end
+  Set.new(relative_files)
+rescue JekyllObsidian::RawHtmlManifest::Invalid => exception
+  fail_audit("raw HTML manifest has an unsupported schema: #{exception.message}")
+end
+
+site_dir = File.expand_path(ARGV.fetch(0, File.expand_path("../_site", __dir__)))
+fail_audit("#{site_dir} is not a directory") unless File.directory?(site_dir)
+fail_audit("the site root must not be a symbolic link") if File.lstat(site_dir).symlink?
+fail_audit("index.html is missing") unless File.file?(File.join(site_dir, "index.html"))
+raw_html_files = raw_html_output_files(site_dir)
+
+root = Pathname.new(site_dir)
+total = 0
+Find.find(site_dir) do |path|
+  next if path == site_dir
+
+  stat = File.lstat(path)
+  relative = Pathname.new(path).relative_path_from(root).to_s
+  unless relative.valid_encoding? && !relative.match?(/[\x00-\x1f\x7f\\]/) &&
+      !relative.start_with?("/") && relative.split("/").none? { |segment| segment.empty? || segment == "." || segment == ".." }
+    fail_audit("unsafe output path: #{relative.inspect}")
+  end
+
+  fail_audit("symbolic link found: #{relative}") if stat.symlink?
+  next if stat.directory?
+  fail_audit("non-regular output found: #{relative}") unless stat.file?
+
+  localized_artifact = relative.match?(%r{\Aassets/website/i18n/[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*/(?:catalog|graph|search)\.v1\.json\z}) ||
+    relative.match?(%r{\A[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*/feed\.xml\z})
+  allowed = EXACT_FILES.include?(relative) || raw_html_files.include?(relative) || localized_artifact || relative.end_with?("/index.html") ||
+    generated_markdown_resource?(site_dir, relative) || ALLOWED_EXTENSIONS.include?(File.extname(relative).downcase)
+  fail_audit("output is not on the extension allowlist: #{relative}") unless allowed
+
+  total += stat.size
+  fail_audit("site is larger than 1 GB (#{total} bytes)") if total > MAX_BYTES
+end
+
+puts "site audit: ok (#{(total + 1023) / 1024} KiB)"

data/website/scripts/templates/pages.yml

@@ -0,0 +1,55 @@
+name: Build and deploy Pages
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event_name != 'push' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+      - name: Read Pages metadata
+        if: github.event_name != 'pull_request'
+        id: pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d
+      - name: Build the site
+        id: build
+        uses: wowfun/jekyll-obsidian@v__JEKYLL_OBSIDIAN_VERSION__
+        with:
+          url: ${{ steps.pages.outputs.origin || 'https://example.invalid' }}
+          baseurl: ${{ github.event_name == 'pull_request' && '/preview' || steps.pages.outputs.base_path }}
+      - name: Upload the site
+        if: github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9
+        with:
+          path: ${{ steps.build.outputs.site-path }}
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128