Template Processing

/** Template engines supported by Eleventy */
type TemplateEngine = 
  | 'liquid'     // Shopify Liquid templating
  | 'njk'        // Mozilla Nunjucks templating  
  | 'md'         // Markdown with front matter
  | 'html'       // Static HTML files
  | '11ty.js'    // JavaScript templates (.11ty.js)
  | 'hbs'        // Handlebars (via plugin)
  | 'mustache'   // Mustache (via plugin)
  | 'ejs'        // EJS (via plugin)
  | 'pug'        // Pug (via plugin)
  | 'webc';      // WebC (via plugin)

/** Template format configuration */
interface TemplateFormat {
  /** File extension */
  extension: string;
  /** Template engine key */
  key: string;
  /** Output file extension */
  outputFileExtension?: string;
}

/**
 * Override template engine library instance
 * @param engineName - Engine name (liquid, njk, etc.)
 * @param libraryInstance - Custom library instance
 */
setLibrary(engineName: string, libraryInstance: any): void;

/**
 * Modify template engine library after creation
 * @param engineName - Engine name to modify
 * @param callback - Function to modify library instance
 */
amendLibrary(engineName: string, callback: (library: any) => void): void;

/**
 * Set Liquid template engine options
 * @param options - Liquid configuration options
 */
setLiquidOptions(options: any): void;

/**
 * Set Liquid parameter parsing behavior
 * @param behavior - Parameter parsing mode
 */
setLiquidParameterParsing(behavior: 'legacy' | 'builtin'): void;

/**
 * Set Nunjucks environment options
 * @param options - Nunjucks environment configuration
 */
setNunjucksEnvironmentOptions(options: any): void;

/**
 * Set precompiled Nunjucks templates
 * @param templates - Precompiled template object
 */
setNunjucksPrecompiledTemplates(templates: any): void;

// Configure Liquid options
eleventyConfig.setLiquidOptions({
  dynamicPartials: false,
  strictFilters: true
});

// Configure Nunjucks environment
eleventyConfig.setNunjucksEnvironmentOptions({
  throwOnUndefined: true,
  autoescape: false
});

// Override Markdown library
const markdownIt = require("markdown-it");
const md = markdownIt({
  html: true,
  breaks: true,
  linkify: true
});
eleventyConfig.setLibrary("md", md);

// Amend existing library
eleventyConfig.amendLibrary("md", (mdLib) => {
  mdLib.use(require("markdown-it-anchor"));
  mdLib.use(require("markdown-it-table-of-contents"));
});

interface LiquidConfiguration {
  /** Liquid engine options */
  options?: {
    /** Enable dynamic partials */
    dynamicPartials?: boolean;
    /** Strict filter mode */
    strictFilters?: boolean;
    /** Strict variables mode */
    strictVariables?: boolean;
    /** Date format */
    dateFormat?: string;
  };
  
  /** Custom Liquid tags */
  tags?: Record<string, Function>;
  
  /** Liquid-specific filters */
  filters?: Record<string, Function>;
  
  /** Liquid-specific shortcodes */
  shortcodes?: Record<string, Function>;
  
  /** Liquid-specific paired shortcodes */
  pairedShortcodes?: Record<string, Function>;
  
  /** Parameter parsing mode */
  parameterParsing?: 'legacy' | 'builtin';
}

interface NunjucksConfiguration {
  /** Nunjucks environment options */
  environmentOptions?: {
    /** Development mode for better errors */
    dev?: boolean;
    /** Throw on undefined variables */
    throwOnUndefined?: boolean;
    /** Auto-escape HTML */
    autoescape?: boolean;
    /** Trim blocks */
    trimBlocks?: boolean;
    /** Left strip blocks */
    lstripBlocks?: boolean;
  };
  
  /** Precompiled templates */
  precompiledTemplates?: Record<string, any>;
  
  /** Nunjucks-specific filters */
  filters?: Record<string, Function>;
  
  /** Nunjucks async filters */
  asyncFilters?: Record<string, Function>;
  
  /** Custom Nunjucks tags */
  tags?: Record<string, Function>;
  
  /** Global variables */
  globals?: Record<string, any>;
  
  /** Nunjucks-specific shortcodes */
  shortcodes?: Record<string, Function>;
  
  /** Nunjucks-specific paired shortcodes */
  pairedShortcodes?: Record<string, Function>;
  
  /** Nunjucks async shortcodes */
  asyncShortcodes?: Record<string, Function>;
  
  /** Nunjucks async paired shortcodes */
  asyncPairedShortcodes?: Record<string, Function>;
}

/**
 * Add global variable to Nunjucks templates
 * @param name - Global variable name
 * @param globalType - Variable value or function
 */
addNunjucksGlobal(name: string, globalType: any): void;

interface JavaScriptConfiguration {
  /** JavaScript functions (filters and shortcodes combined) */
  functions?: Record<string, Function>;
  
  /** JavaScript-specific filters */
  filters?: Record<string, Function>;
  
  /** JavaScript-specific shortcodes */
  shortcodes?: Record<string, Function>;
  
  /** JavaScript-specific paired shortcodes */
  pairedShortcodes?: Record<string, Function>;
}

// example.11ty.js
class MyTemplate {
  data() {
    return {
      permalink: "/my-page/",
      title: "My Page"
    };
  }

  render(data) {
    return `<h1>${data.title}</h1>
            <p>Current year: ${new Date().getFullYear()}</p>`;
  }
}

module.exports = MyTemplate;

// Or functional style
module.exports = {
  data: {
    permalink: "/functional-page/",
    title: "Functional Page"
  },
  render: (data) => `<h1>${data.title}</h1>`
};

/**
 * Add custom Markdown highlighter for code blocks
 * @param highlightFn - Function to highlight code blocks
 */
addMarkdownHighlighter(highlightFn: (code: string, language: string) => string): void;

interface MarkdownConfiguration {
  /** Markdown highlighter function */
  markdownHighlighter?: (code: string, language: string) => string;
  
  /** Library overrides for markdown-it */
  libraryOverrides?: {
    md?: any; // markdown-it instance
  };
}

// Add syntax highlighting
eleventyConfig.addMarkdownHighlighter((code, language) => {
  const Prism = require("prismjs");
  const loadLanguages = require("prismjs/components/");
  
  if (language && Prism.languages[language]) {
    loadLanguages([language]);
    return Prism.highlight(code, Prism.languages[language], language);
  }
  return code;
});

// Configure markdown-it
const markdownIt = require("markdown-it");
eleventyConfig.setLibrary("md", markdownIt({
  html: true,
  breaks: true,
  linkify: true
}).use(require("markdown-it-anchor"), {
  permalink: true,
  permalinkBefore: true,
  permalinkSymbol: "#"
}));

/**
 * Set whether to deep merge data objects
 * @param deepMerge - Enable/disable deep merging
 */
setDataDeepMerge(deepMerge: boolean): void;

/**
 * Set front matter parsing options
 * @param options - Front matter parsing configuration
 */
setFrontMatterParsingOptions(options?: FrontMatterOptions): void;

interface FrontMatterOptions {
  /** Default language for front matter */
  language?: 'yaml' | 'json' | 'js' | 'javascript';
  
  /** Custom parsing engines */
  engines?: {
    yaml?: Function;
    json?: Function;
    javascript?: Function;
    js?: Function;
  };
}

/**
 * Add custom date parsing callback
 * @param callback - Date parsing function
 */
addDateParsing(callback: (dateValue: any) => Date | null): void;

// Enable deep merging of data
eleventyConfig.setDataDeepMerge(true);

// Configure front matter parsing
eleventyConfig.setFrontMatterParsingOptions({
  language: "yaml",
  engines: {
    yaml: require("js-yaml").load,
    javascript: require("./custom-js-parser")
  }
});

// Add custom date parsing
eleventyConfig.addDateParsing((dateValue) => {
  if (typeof dateValue === "string" && dateValue.match(/^\d{4}-\d{2}-\d{2}$/)) {
    return new Date(dateValue + "T00:00:00.000Z");
  }
  return null;
});

interface UniversalConfiguration {
  /** Universal filters (work in all engines) */
  filters?: Record<string, Function>;
  
  /** Universal shortcodes (work in all engines) */
  shortcodes?: Record<string, Function>;
  
  /** Universal paired shortcodes (work in all engines) */
  pairedShortcodes?: Record<string, Function>;
}

/**
 * Set dynamic permalinks behavior
 * @param enabled - Enable/disable dynamic permalinks
 */
setDynamicPermalinks(enabled: boolean): void;

/**
 * Add virtual template (in-memory template)
 * @param virtualInputPath - Virtual path for template
 * @param content - Template content
 * @param data - Template data
 */
addTemplate(virtualInputPath: string, content: string, data?: any): void;

/**
 * Check if path is a virtual template
 * @param virtualInputPath - Path to check
 * @returns Whether path is virtual template
 */
isVirtualTemplate(virtualInputPath: string): boolean;

// Add virtual templates
eleventyConfig.addTemplate("virtual-page.md", `
---
title: Virtual Page
---
# {{ title }}

This page exists only in memory.
`, { permalink: "/virtual/" });

// Check virtual templates
if (eleventyConfig.isVirtualTemplate("virtual-page.md")) {
  console.log("This is a virtual template");
}

// Configure permalinks
eleventyConfig.setDynamicPermalinks(true);

/**
 * Configure layout resolution behavior
 * @param resolution - Enable/disable extension-less layout files
 */
setLayoutResolution(resolution: boolean): void;

/**
 * Add layout alias for easier referencing
 * @param from - Alias name
 * @param to - Actual layout path
 */
addLayoutAlias(from: string, to: string): void;

/**
 * Configure template cache usage
 * @param bypass - Enable/disable template caching
 */
setUseTemplateCache(bypass: boolean): void;

// Configure layouts
eleventyConfig.setLayoutResolution(true); // Allow extension-less layouts
eleventyConfig.addLayoutAlias("post", "layouts/post.njk");
eleventyConfig.addLayoutAlias("page", "layouts/page.liquid");

// Template caching
eleventyConfig.setUseTemplateCache(true); // Enable caching for performance

type TemplateEngine = 
  | 'liquid' | 'njk' | 'md' | 'html' | '11ty.js' 
  | 'hbs' | 'mustache' | 'ejs' | 'pug' | 'webc';

interface TemplateFormat {
  extension: string;
  key: string;
  outputFileExtension?: string;
}

interface FrontMatterOptions {
  language?: 'yaml' | 'json' | 'js' | 'javascript';
  engines?: {
    yaml?: (content: string) => any;
    json?: (content: string) => any;
    javascript?: (content: string) => any;
    js?: (content: string) => any;
  };
}

interface EngineConfiguration {
  liquid?: LiquidConfiguration;
  nunjucks?: NunjucksConfiguration;
  javascript?: JavaScriptConfiguration;
  markdown?: MarkdownConfiguration;
  universal?: UniversalConfiguration;
}