API Reference

export default function(eleventyConfig) {
  // Configuration options
  return {
    dir: {
      input: "src",
      output: "_site",
      includes: "_includes",
      data: "_data"
    },
    markdownTemplateEngine: "njk",
    htmlTemplateEngine: "njk",
    passthroughFileCopy: true
  };
}

eleventyConfig.addWatchTarget("src/_data");
eleventyConfig.addWatchTarget("src/sass");
eleventyConfig.addWatchTarget(`themes/${activeTheme}`);
eleventyConfig.addWatchTarget(localContentPath);

// Copy assets
eleventyConfig.addPassthroughCopy({ "src/assets": "/assets" });

// Copy admin interface
eleventyConfig.addPassthroughCopy({ "src/admin": "/admin" });

// Copy content media
eleventyConfig.addPassthroughCopy({ "src/content/posts": "/content/posts" });

// In templates
{{ post.date | date("dd LLLL yyyy") }}
{{ post.date | date("yyyy-MM-dd") }}
{{ post.date | date("dd/MM/yyyy") }}

<time datetime="{{ post.date | date('yyyy-MM-dd') }}">
  {{ post.date | date("dd LLLL yyyy") }}
</time>

// In templates
{{ "My Post Title" | slugify }}
// Output: "my-post-title"

{{ "Hello World!" | slugify }}
// Output: "hello-world"

// In templates
{{ "partials/documentation/example.md" | includeMarkdown }}

<div class="documentation-section">
  {{ "partials/documentation/intro.md" | includeMarkdown }}
</div>

// In templates
{{ collections.posts | sortBy("date", "desc") }}
{{ collections.posts | sortBy("data.title", "asc") }}
{{ projects | sortBy("featured", "desc") }}

<!-- Sort posts by date (newest first) -->
{% for post in collections.posts | sortBy("date", "desc") %}
  <article>{{ post.data.title }}</article>
{% endfor %}

<!-- Sort by title alphabetically -->
{% for page in collections.documentation | sortBy("data.title", "asc") %}
  <h3>{{ page.data.title }}</h3>
{% endfor %}

<!-- Sort by custom field -->
{% for project in collections.projects | sortBy("data.featured", "desc") %}
  <div>{{ project.data.name }}</div>
{% endfor %}

// In templates
{{ collections.posts | limit(5) }}
{{ recentPosts | limit(3) }}

<!-- Show only the 5 most recent posts -->
{% for post in collections.posts | sortBy("date", "desc") | limit(5) %}
  <article>{{ post.data.title }}</article>
{% endfor %}

// In templates
{{ collections.posts | offset(3) }}
{{ allItems | offset(10) }}

<!-- Skip the first 3 posts (for pagination) -->
{% for post in collections.posts | sortBy("date", "desc") | offset(3) %}
  <article>{{ post.data.title }}</article>
{% endfor %}

<!-- Sort by date, skip first 5, then show next 10 -->
{% for post in collections.posts | sortBy("date", "desc") | offset(5) | limit(10) %}
  <article>
    <h3>{{ post.data.title }}</h3>
    <time>{{ post.date | date("dd LLLL yyyy") }}</time>
  </article>
{% endfor %}

<!-- Featured projects first, then limit to 6 -->
{% for project in collections.projects | sortBy("data.featured", "desc") | limit(6) %}
  <div class="project">{{ project.data.name }}</div>
{% endfor %}

<!-- Pagination example -->
{% set pageSize = 10 %}
{% set currentPage = 1 %}
{% set offset = (currentPage - 1) * pageSize %}
{% for post in collections.posts | sortBy("date", "desc") | offset(offset) | limit(pageSize) %}
  <article>{{ post.data.title }}</article>
{% endfor %}

// Available in all templates
{{ site.name }}           // "Quesby - Boilerplate"
{{ site.url }}            // "https://theoddape.it"
{{ site.description }}    // "An Eleventy boilerplate with Decap CMS"
{{ site.logo }}           // "/assets/images/quesby-logo.svg"
{{ site.favicon }}        // "/assets/images/quesby-logo.png"
{{ site.theme }}          // "quesby-core"
{{ site.defaultVisualTheme }} // "dark"
{{ site.contentPath }}    // "${QUESBY_CONTENT_PATH}"

// Available in all templates
{{ theme }} // "quesby-core" or "quesby-brand-website"

// Permalink computation
eleventyComputed: {
  permalink: (data) => {
    const input = (data.page?.inputPath || "").replace(/\\/g, "/");
    if (input.includes("/content/posts/")) {
      const slug = data.slug || data.page.fileSlug;
      return `/blog/${slug}/`;
    }
    if (input.includes("/content/documentation/")) {
      const slug = data.slug || data.page.fileSlug;
      return `/documentation/${slug}/`;
    }
    return data.permalink;
  }
}

// In templates
{% raw %}
{% for post in collections.posts %}
  <article>
    <h1><a href="{{ post.url }}">{{ post.data.title }}</a></h1>
    <time>{{ post.data.date | date("dd LLLL yyyy") }}</time>
    <p>{{ post.data.description }}</p>
  </article>
{% endfor %}
{% endraw %}

{% image "path/to/image.jpg", "Alt text", "sizes" %}

{% image "hero/cover.jpg", "Site hero image", "(min-width: 768px) 75vw, 100vw" %}

{% svg "path/to/icon.svg", "css-classes" %}

{% svg "assets/icons/github.svg", "w-6 h-6 text-gray-600" %}

// Available in all templates
{{ page.url }}           // Current page URL
{{ page.inputPath }}     // Source file path
{{ page.fileSlug }}      // File slug
{{ page.filePathStem }}  // File path without extension
{{ page.date }}          // Page date
{{ page.outputPath }}    // Output file path

// Available in content templates
{{ title }}              // Page title
{{ description }}        // Page description
{{ date }}               // Publication date
{{ author }}             // Author name
{{ tags }}               // Array of tags
{{ draft }}              // Draft status
{{ content }}            // Rendered content

# In src/admin/config.yml
collections:
  - name: "posts"
    fields:
      - {label: "ULID", name: "ulid", widget: "ulid"}

- {label: "Title", name: "title", widget: "string"}
- {label: "Title", name: "title", widget: "string", required: true}
- {label: "Title", name: "title", widget: "string", default: "Default Title"}

- {label: "Description", name: "description", widget: "text"}
- {label: "Description", name: "description", widget: "text", hint: "Brief description"}

- {label: "Body", name: "body", widget: "markdown"}
- {label: "Body", name: "body", widget: "markdown", buttons: ["bold", "italic", "link"]}

- {label: "Date", name: "date", widget: "datetime"}
- {label: "Date", name: "date", widget: "datetime", format: "YYYY-MM-DD"}

- {label: "Draft", name: "draft", widget: "boolean"}
- {label: "Draft", name: "draft", widget: "boolean", default: true}

- {label: "Tags", name: "tags", widget: "list"}
- {label: "Tags", name: "tags", widget: "list", allow_add: true}

- {label: "Image", name: "image", widget: "image"}
- {label: "Image", name: "image", widget: "image", media_library: {config: {multiple: false}}}

- {label: "Status", name: "status", widget: "select", options: ["draft", "published", "archived"]}

- {label: "Price", name: "price", widget: "number"}
- {label: "Price", name: "price", widget: "number", value_type: "float", min: 0}

- {label: "ID", name: "id", widget: "ulid"}

collections:
  - name: "posts"
    fields:
      - {label: "ID", name: "id", widget: "ulid"}
      - {label: "Title", name: "title", widget: "string"}
      # ... other fields

{
  "scripts": {
    "dev": "eleventy --serve",
    "serve": "concurrently \"pnpm run css:watch\" \"npx @11ty/eleventy --serve\"",
    "serve:no-watch": "npx @11ty/eleventy --watch"
  }
}

{
  "scripts": {
    "build": "eleventy",
    "build:css": "node scripts/build.js",
    "build:prod": "NODE_ENV=production pnpm run build"
  }
}

{
  "scripts": {
    "watch:css": "node scripts/watch.js",
    "build:css": "node scripts/build.js",
    "gen:ec-css": "node scripts/gen-ec-css.js"
  }
}

import { execSync } from 'child_process'
import fs from 'fs'

const siteData = JSON.parse(fs.readFileSync('./src/_data/site.json', 'utf-8'))
const theme = siteData.theme || 'default'
const command = `sass src/sass:src/assets/css src/themes/${theme}:src/assets/css --style=compressed`

execSync(command, { stdio: 'inherit' })

import { execSync } from 'child_process'
import fs from 'fs'

const siteData = JSON.parse(fs.readFileSync('./src/_data/site.json', 'utf-8'))
const theme = siteData.theme || 'default'
const command = `sass --watch src/sass:src/assets/css src/themes/${theme}:src/assets/css --style=compressed`

execSync(command, { stdio: 'inherit' })

import { ExpressiveCodeEngine } from '@expressive-code/core';
import { pluginShiki } from '@expressive-code/plugin-shiki';

const engine = new ExpressiveCodeEngine({
  plugins: [
    pluginShiki({
      themes: ['github-light', 'github-dark']
    })
  ]
});

const styles = await engine.getBaseStyles();
const themeStyles = await engine.getThemeStyles();
const fullStyles = styles + '\n' + themeStyles;

fs.writeFileSync(outPath, fullStyles, 'utf8');

// In eleventy.config.js
function expandEnv(str) {
  if (typeof str !== "string") return str;
  return str.replace(/\$\{([^}]+)\}/g, (_, key) => process.env[key] ?? "");
}

// Usage
const contentPath = expandEnv("${QUESBY_CONTENT_PATH}");
// Result: "/path/to/content" or fallback value

@mixin font($properties) {
  font-style: map.get($properties, style);
  font-variant: map.get($properties, variant);
  font-weight: map.get($properties, weight);
  font-size: map.get($properties, size);
  line-height: map.get($properties, lineHeight);
  font-family: map.get($properties, family);
  text-transform: map.get($properties, transform);
}

@mixin flex-container(
  $direction: row,
  $justify: flex-start,
  $items: stretch,
  $content: stretch,
  $wrap: nowrap
) {
  display: flex;
  flex-direction: $direction;
  justify-content: $justify;
  align-items: $items;
  align-content: $content;
  flex-wrap: $wrap;
}

@mixin sliding-background($color, $duration: 0.3s) {
  display: inline-block;
  position: relative;
  overflow: hidden;
  color: #fff;

  &:before {
    content: "";
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    background-color: $color;
    z-index: -1;
    transition: transform $duration;
    transform-origin: left;
    transform: scaleX(0);
  }

  &:hover:before {
    transform: scaleX(1);
  }
}

// In base.njk template
<script>
  (function(){
    var ls = localStorage.getItem('theme');
    var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    var root = document.documentElement;
    if (ls === 'dark' || (!ls && prefersDark)) root.classList.add('dark');
  })();
</script>

// In eleventy.config.js
function setupContentDirectory() {
  const raw = expandEnv(site.contentPath);
  const resolvedRaw = raw && raw.trim().length ? raw : "content";

  const contentPath = path.isAbsolute(resolvedRaw)
    ? resolvedRaw
    : path.resolve(process.cwd(), resolvedRaw);

  if (!fs.existsSync(contentPath)) {
    throw new Error(`Content path not found: ${contentPath}`);
  }

  const localContentDir = path.join(process.cwd(), "src", "content");

  if (!fs.existsSync(localContentDir) || fs.readdirSync(localContentDir).length === 0) {
    copyDirectoryRecursive(contentPath, localContentDir);
  }

  return localContentDir;
}

// In eleventy.config.js
function copyDirectoryRecursive(source, destination) {
  try {
    if (!fs.existsSync(destination)) {
      fs.mkdirSync(destination, { recursive: true });
    }

    const items = fs.readdirSync(source);

    for (const item of items) {
      const sourcePath = path.join(source, item);
      const destPath = path.join(destination, item);

      if (fs.statSync(sourcePath).isDirectory()) {
        copyDirectoryRecursive(sourcePath, destPath);
      } else {
        fs.copyFileSync(sourcePath, destPath);
      }
    }
  } catch (error) {
    console.error(`Error during copy: ${error.message}`);
    throw error;
  }
}

// In eleventy.config.js
const processor = unified()
  .use(remarkParse)
  .use(remarkGfm)
  .use(remarkRehype)
  .use(rehypeExpressiveCode, {
    themes: ['github-light', 'github-dark'],
    defaultProps: {
      wrap: true
    }
  })
  .use(rehypeStringify);

eleventyConfig.setLibrary("md", {
  async render(str) {
    const result = await processor.process(str);
    return result.toString();
  }
});

// In eleventy.config.js
const md = new MarkdownIt({
  html: true,
  breaks: true,
  linkify: true
}).use(MarkdownItLinkAttributes, {
  pattern: /^https?:/,
  attrs: {
    target: '_blank',
    rel: 'noopener'
  }
});

// In eleventy.config.js
import * as cheerio from 'cheerio';

eleventyConfig.addTransform("addHeadingIdsAndTOC", function(content, outputPath) {
  // Only process HTML files in documentation
  if (outputPath && outputPath.endsWith('.html') && outputPath.includes('/documentation/')) {
    console.log(`Adding heading IDs and TOC for: ${outputPath}`);

    // Parse HTML with Cheerio
    const $ = cheerio.load(content);
    const headings = [];
    let headingCount = 0;

    // Find all h2 elements and add IDs
    $('h2').each(function() {
      const $heading = $(this);
      const title = $heading.text().trim();

      // Skip if already has an ID
      if ($heading.attr('id')) {
        return;
      }

      // Generate anchor from title
      const anchor = title
        .toLowerCase()
        .replace(/[^\w\s-]/g, '')
        .replace(/\s+/g, '-')
        .trim();

      // Add ID to heading
      $heading.attr('id', anchor);
      headingCount++;

      // Add to headings array for TOC
      headings.push({
        title: title,
        anchor: anchor
      });
    });

    // Generate TOC HTML if we have headings
    if (headings.length > 0) {
      let tocHTML = '<nav class="documentation-toc">\n';
      tocHTML += '  <h3>On this page</h3>\n';
      tocHTML += '  <ul>\n';

      headings.forEach(heading => {
        tocHTML += `    <li>\n`;
        tocHTML += `      <a href="#${heading.anchor}">${heading.title}</a>\n`;
        tocHTML += `    </li>\n`;
      });

      tocHTML += '  </ul>\n';
      tocHTML += '</nav>';

      // Replace the TOC placeholder in the aside
      $('nav.documentation-toc').replaceWith(tocHTML);

      console.log(`Added IDs to ${headingCount} headings and inserted TOC for ${outputPath}`);
    }

    return $.html();
  }

  return content;
});

// In eleventy.config.js
if (!fs.existsSync(contentPath)) {
  throw new Error(
    `❌ Content path not found:\n${contentPath}\n\n` +
    `Check your contentPath in site.json or the .env variable QUESBY_CONTENT_PATH`
  );
}

// In includeMarkdown filter
try {
  const fullPath = path.join(process.cwd(), 'src', '_includes', markdownPath);

  if (fs.existsSync(fullPath)) {
    const markdownContent = fs.readFileSync(fullPath, 'utf-8');
    const result = await processor.process(markdownContent);
    return result.toString();
  } else {
    console.warn(`⚠️  Markdown file not found: ${fullPath}`);
    return `<p>⚠️ Content not found: ${markdownPath}</p>`;
  }
} catch (error) {
  console.error(`❌ Error loading ${markdownPath}:`, error);
  return `<p>❌ Error loading content</p>`;
}

// Production CSS compilation
const command = `sass --no-source-map --style=compressed src/sass:src/assets/css src/themes/${theme}:src/assets/css`;

// Image optimization (available but not enabled by default)
// To enable, uncomment and install @11ty/eleventy-img
eleventyConfig.addNunjucksAsyncShortcode("image", async function(src, alt, sizes) {
  let stats = await Image(src, {
    widths: [300, 600, 900],
    formats: ["webp", "jpeg"],
    outputDir: "./_site/assets/images/"
  });
  return `<img src="${stats.webp[0].url}" alt="${alt}" sizes="${sizes}">`;
});