.eleventy.js

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");
const markdownIt = require("markdown-it");
const markdownItAnchor = require("markdown-it-anchor");
const markdownItTaskLists = require("markdown-it-task-lists");
const pluginSitemap = require("@quasibit/eleventy-plugin-sitemap");
const fs = require("fs");
const crypto = require("crypto");
const path = require("path");

module.exports = function (eleventyConfig) {
  // ── Plugins ──────────────────────────────────────────────────────────────
  eleventyConfig.addPlugin(syntaxHighlight);
  eleventyConfig.addPlugin(pluginSitemap, {
    sitemap: {
      hostname: "https://www.postgis-python.com",
    },
  });

  // ── Markdown config ───────────────────────────────────────────────────────
  const md = markdownIt({ html: true, linkify: true, typographer: true })
    .use(markdownItAnchor, {
      permalink: markdownItAnchor.permalink.headerLink({ safariReaderFix: true }),
      slugify: (s) =>
        s.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-"),
    })
    .use(markdownItTaskLists, { enabled: true, label: true, labelAfter: true });

  eleventyConfig.setLibrary("md", md);

  // ── Passthrough copies ────────────────────────────────────────────────────
  eleventyConfig.addPassthroughCopy("assets");
  eleventyConfig.addPassthroughCopy({ "assets/icons/favicon.ico": "favicon.ico" });
  eleventyConfig.addPassthroughCopy({ "assets/manifest.json": "manifest.json" });
  eleventyConfig.addPassthroughCopy({ "assets/sw.js": "sw.js" });
  eleventyConfig.addPassthroughCopy("_headers");

  // ── Filters ───────────────────────────────────────────────────────────────
  // Build breadcrumb data from a page URL
  eleventyConfig.addFilter("breadcrumbs", function (url) {
    const labels = {
      "advanced-gist-indexing-optimization": "Advanced GiST Indexing",
      "mastering-core-spatial-query-patterns": "Core Spatial Queries",
      "sqlalchemy-and-geoalchemy-integration-workflows": "SQLAlchemy & GeoAlchemy",
      "partial-gist-indexes": "Partial GiST Indexes",
      "composite-spatial-indexes": "Composite Spatial Indexes",
      "index-only-scan-strategies": "Index-Only Scan Strategies",
      "query-plan-analysis-with-explain": "Query Plan Analysis",
      "bounding-box-filtering": "Bounding Box Filtering",
      "knn-nearest-neighbor-queries": "KNN Nearest Neighbor",
      "spatial-joins": "Spatial Joins",
      "st_dwithin-radius-searches": "ST_DWithin Radius Searches",
      "model-mapping-with-geoalchemy2": "Model Mapping with GeoAlchemy2",
      "session-management-for-spatial-data": "Session Management",
      "hybrid-properties-for-geometry": "Hybrid Properties",
      "type-coercion-and-serialization": "Type Coercion & Serialization",
      "creating-partial-indexes-for-active-map-regions": "Creating Partial Indexes for Active Map Regions",
      "composite-indexes-for-geometry-and-timestamp-columns": "Composite Indexes for Geometry & Timestamp Columns",
      "leveraging-index-only-scans-for-point-data": "Leveraging Index-Only Scans for Point Data",
      "reading-explain-analyze-output-for-spatial-joins": "Reading EXPLAIN ANALYZE Output for Spatial Joins",
      "optimizing-bounding-box-queries-with-operator": "Optimizing Bounding Box Queries with && Operator",
      "implementing-knn-search-with-operator": "Implementing KNN Search with <-> Operator",
      "batch-processing-spatial-joins-in-python": "Batch Processing Spatial Joins in Python",
      "tuning-st_dwithin-for-high-traffic-apis": "Tuning ST_DWithin for High-Traffic APIs",
      "configuring-geoalchemy2-geometry-columns-in-fastapi": "Configuring GeoAlchemy2 Geometry Columns in FastAPI",
      "handling-session-timeouts-during-bulk-spatial-inserts": "Handling Session Timeouts During Bulk Spatial Inserts",
      // ── Additional top-level section labels ──
      "spatial-schema-migrations-and-evolution": "Spatial Schema Migrations",
      "spatial-performance-monitoring-and-observability": "Performance Monitoring",
      tools: "Tools",
      // ── Additional section labels ──
      "adding-geometry-columns-to-live-tables": "Adding Geometry Columns to Live Tables",
      "in-place-srid-reprojection": "In-Place SRID Reprojection",
      "concurrent-index-builds": "Concurrent Index Builds",
      "backfilling-and-zero-downtime-migrations": "Backfilling & Zero-Downtime Migrations",
      "pg-stat-statements-for-spatial-workloads": "pg_stat_statements for Spatial Workloads",
      "detecting-gist-index-bloat": "Detecting GiST Index Bloat",
      "autovacuum-tuning-for-geometry-tables": "Autovacuum Tuning for Geometry Tables",
      "choosing-a-spatial-index-type": "Choosing a Spatial Index Type",
      "choosing-a-postgis-driver": "Choosing a PostGIS Driver",
      // ── Maturity-phase topics ──
      "geometry-validity-and-repair": "Geometry Validity and Repair",
      "spatial-table-partitioning": "Spatial Table Partitioning",
      "alembic-for-spatial-schemas": "Alembic for Spatial Schemas",
      "materialized-views-for-spatial-caching": "Materialized Views for Spatial Caching",
      // ── Maturity-phase guides ──
      "detecting-invalid-geometries-at-scale": "Detecting Invalid Geometries at Scale",
      "st-makevalid-strategies-for-polygon-repair": "ST_MakeValid Strategies for Polygon Repair",
      "enforcing-validity-with-check-constraints": "Enforcing Validity With Check Constraints",
      "repairing-geometry-during-python-imports": "Repairing Geometry During Python Imports",
      "partitioning-spatial-tables-by-time-range": "Partitioning Spatial Tables by Time Range",
      "list-partitioning-spatial-data-by-region": "List Partitioning Spatial Data by Region",
      "indexing-and-planning-on-partitioned-spatial-tables": "Indexing and Planning on Partitioned Spatial Tables",
      "gist-vs-sp-gist-vs-brin-for-spatial-columns": "GiST vs SP-GiST vs BRIN for Spatial Columns",
      "clustering-a-table-on-its-spatial-index": "Clustering a Table on Its Spatial Index",
      "st-intersects-vs-st-contains-vs-st-within": "ST_Intersects vs ST_Contains vs ST_Within",
      "st-subdivide-for-oversized-polygons": "ST_Subdivide for Oversized Polygons",
      "filtered-knn-when-the-index-cannot-help": "Filtered KNN When the Index Cannot Help",
      "geography-vs-geometry-for-radius-queries": "Geography vs Geometry for Radius Queries",
      "autogenerating-spatial-migrations-with-alembic": "Autogenerating Spatial Migrations With Alembic",
      "running-create-index-concurrently-from-alembic": "Running CREATE INDEX CONCURRENTLY From Alembic",
      "writing-reversible-geometry-migrations": "Writing Reversible Geometry Migrations",
      "asyncpg-for-spatial-workloads": "asyncpg for Spatial Workloads",
      "bulk-loading-geometries-with-copy": "Bulk Loading Geometries With COPY",
      "streaming-geojson-responses-without-buffering": "Streaming GeoJSON Responses Without Buffering",
      "caching-tile-queries-with-materialized-views": "Caching Tile Queries With Materialized Views",
      "refreshing-materialized-views-concurrently": "Refreshing Materialized Views Concurrently",
      "choosing-between-a-cache-and-an-index": "Choosing Between a Cache and an Index",
      "finding-unused-spatial-indexes": "Finding Unused Spatial Indexes",
      "alerting-on-spatial-query-regressions": "Alerting on Spatial Query Regressions",
      "vacuum-freeze-and-geometry-toast-tables": "VACUUM FREEZE and Geometry TOAST Tables",
      "auditing-srid-consistency-across-a-database": "Auditing SRID Consistency Across a Database",
      "rolling-back-a-failed-spatial-migration": "Rolling Back a Failed Spatial Migration",
      "dropping-a-spatial-index-safely": "Dropping a Spatial Index Safely",
      // ── Additional deep-dive page labels ──
      "alter-table-add-geometry-column-without-locking": "ALTER TABLE ADD COLUMN Geometry Without Locking",
      "batch-st_transform-reprojection-in-python": "Batch ST_Transform Reprojection in Python",
      "create-index-concurrently-on-large-spatial-tables": "CREATE INDEX CONCURRENTLY on Large Spatial Tables",
      "backfilling-geometry-from-latitude-longitude-columns": "Backfilling Geometry From Latitude/Longitude Columns",
      "finding-slow-st-function-calls-with-pg-stat-statements": "Finding Slow ST_ Function Calls with pg_stat_statements",
      "measuring-gist-index-bloat-with-pgstattuple": "Measuring GiST Index Bloat with pgstattuple",
      "automating-vacuum-analyze-for-geometry-heavy-tables": "Automating VACUUM ANALYZE for Geometry-Heavy Tables",
      "brin-indexes-for-append-only-spatial-tables": "BRIN Indexes for Append-Only Spatial Tables",
      "covering-indexes-with-include-for-spatial-queries": "Covering Indexes with INCLUDE for Spatial Queries",
      "forcing-index-scans-when-the-planner-chooses-seq-scan": "Forcing Index Scans When the Planner Chooses Seq Scan",
      "keyset-pagination-for-knn-result-sets": "Keyset Pagination for KNN Result Sets",
      "point-in-polygon-joins-at-scale": "Point-in-Polygon Joins at Scale",
      "tile-based-bounding-box-queries-for-web-maps": "Tile-Based Bounding Box Queries for Web Maps",
      "st_dwithin-vs-st_distance-for-proximity-filtering": "ST_DWithin vs ST_Distance for Proximity Filtering",
      "migrating-spatial-code-from-psycopg2-to-psycopg3": "Migrating Spatial Code from psycopg2 to psycopg3",
      "spatial-aggregations-with-hybrid-expressions": "Spatial Aggregations with Hybrid Expressions",
      "geoalchemy2-vs-raw-wkb-when-to-use-each": "GeoAlchemy2 vs Raw WKB: When to Use Each",
      "async-streaming-of-large-geometry-result-sets": "Async Streaming of Large Geometry Result Sets",
      offline: "Offline",
    };
    const crumbs = [{ label: "Home", url: "/" }];
    const parts = url.replace(/^\/|\/$/g, "").split("/").filter(Boolean);
    let cumulative = "";
    for (const part of parts) {
      cumulative += "/" + part;
      crumbs.push({ label: labels[part] || part, url: cumulative + "/" });
    }
    return crumbs;
  });

  // Cache-bust filter: appends ?v=<8-char md5> so immutable assets get a new URL on change
  eleventyConfig.addFilter("assetHash", function (url) {
    try {
      const filePath = path.join(__dirname, url.replace(/^\//, "").split("?")[0]);
      const hash = crypto.createHash("md5").update(fs.readFileSync(filePath)).digest("hex").slice(0, 8);
      return `${url}?v=${hash}`;
    } catch {
      return url;
    }
  });

  // Truncate filter
  eleventyConfig.addFilter("truncate", function (str, len) {
    if (!str) return "";
    return str.length > len ? str.slice(0, len) + "…" : str;
  });

  // Strip the first <h1>…</h1> from rendered content (layout already shows the title)
  eleventyConfig.addFilter("stripFirstH1", function (content) {
    if (!content) return "";
    return content.replace(/<h1[^>]*>[\s\S]*?<\/h1>/, "");
  });

  // ── Transforms ────────────────────────────────────────────────────────────
  // Wrap tables for horizontal scroll
  eleventyConfig.addTransform("wrapTables", function (content, outputPath) {
    if (outputPath && outputPath.endsWith(".html")) {
      return content.replace(
        /<table>/g,
        '<div class="table-scroll" tabindex="0" role="region" aria-label="table"><table>'
      ).replace(/<\/table>/g, "</table></div>");
    }
    return content;
  });

  // Wrap code blocks server-side to avoid CLS from runtime DOM manipulation
  eleventyConfig.addTransform("wrapCodeBlocks", function (content, outputPath) {
    if (!outputPath || !outputPath.endsWith(".html")) return content;
    // Match the full language-annotated code block (opening through closing) and wrap it
    return content.replace(
      /(<pre class="language-(\w+)"><code class="language-\2">[\s\S]*?<\/code><\/pre>)/g,
      (match, block, lang) => {
        // A horizontally scrollable <pre> must be keyboard reachable (WCAG 2.1.1), so give it
        // a tab stop and an accessible name rather than leaving it focus-blind.
        const focusable = block.replace(
          `<pre class="language-${lang}">`,
          `<pre class="language-${lang}" tabindex="0" role="region" aria-label="${lang} code sample">`
        );
        return `<div class="code-block-wrapper"><span class="code-lang-label">${lang}</span>${focusable}</div>`;
      }
    );
  });

  // Any remaining <pre> (fenced blocks with no language) also scrolls horizontally, so it needs
  // the same keyboard affordance as the highlighted ones.
  eleventyConfig.addTransform("focusablePlainPre", function (content, outputPath) {
    if (!outputPath || !outputPath.endsWith(".html")) return content;
    return content.replace(/<pre(?=[\s>])(?![^>]*tabindex)([^>]*)>/g,
      (m, attrs) => `<pre${attrs} tabindex="0" role="region" aria-label="code sample">`);
  });

  // ── Collections ───────────────────────────────────────────────────────────
  eleventyConfig.addCollection("sections", function (collectionApi) {
    return collectionApi.getFilteredByGlob("content/*/index.md").filter(
      (p) => p.url.split("/").filter(Boolean).length === 1
    );
  });

  // ── Ignore files ─────────────────────────────────────────────────────────
  eleventyConfig.ignores.add("BUILD_CHECKLIST.md");
  eleventyConfig.ignores.add("AGENTS.md");
  eleventyConfig.ignores.add("site_description_and_requirements.md");
  eleventyConfig.ignores.add("README.md");
  eleventyConfig.ignores.add("wrangler.jsonc");
  eleventyConfig.ignores.add("CLAUDE.md");
  eleventyConfig.ignores.add("_plan/**");

  // ── Config ────────────────────────────────────────────────────────────────
  return {
    dir: {
      input: ".",
      includes: "_includes",
      data: "_data",
      output: "_site",
    },
    templateFormats: ["md", "njk", "html"],
    markdownTemplateEngine: "njk",
    htmlTemplateEngine: "njk",
  };
};