@stati/core 1.0.0

package/dist/core/navigation.js

@@ -0,0 +1,181 @@
+import { basename } from 'path';
+/**
+ * Builds a hierarchical navigation structure from pages.
+ * Groups pages by directory structure and sorts them appropriately.
+ *
+ * @param pages - Array of page models to build navigation from
+ * @returns Array of top-level navigation nodes
+ *
+ * @example
+ * ```typescript
+ * const pages = [
+ *   { url: '/blog/post-1', frontMatter: { title: 'Post 1', order: 2 } },
+ *   { url: '/blog/post-2', frontMatter: { title: 'Post 2', order: 1 } },
+ *   { url: '/about', frontMatter: { title: 'About' } }
+ * ];
+ * const nav = buildNavigation(pages);
+ * // Results in hierarchical structure with sorted blog posts
+ * ```
+ */
+export function buildNavigation(pages) {
+    // Group pages by their collection (directory)
+    const collections = new Map();
+    for (const page of pages) {
+        const collectionPath = getCollectionPath(page.url);
+        if (!collections.has(collectionPath)) {
+            collections.set(collectionPath, []);
+        }
+        collections.get(collectionPath).push(page);
+    }
+    const navNodes = [];
+    // Process root-level pages
+    if (collections.has('/')) {
+        const rootPages = collections.get('/').filter((page) => {
+            // Don't include pages that are index pages for other collections
+            const potentialCollectionPath = page.url;
+            return !collections.has(potentialCollectionPath) || page.url === '/';
+        });
+        for (const page of rootPages) {
+            navNodes.push(createNavNodeFromPage(page));
+        }
+    }
+    // Process collection directories
+    for (const [collectionPath, collectionPages] of collections) {
+        if (collectionPath !== '/') {
+            // Find the index page for this collection (if it exists)
+            const indexPage = pages.find((p) => p.url === collectionPath);
+            // Create collection node
+            const collectionNode = createCollectionNode(collectionPath, collectionPages, indexPage);
+            navNodes.push(collectionNode);
+        }
+    }
+    return sortNavigationNodes(navNodes);
+}
+/**
+ * Determines which collection a page belongs to based on its URL
+ */
+function getCollectionPath(url) {
+    const pathParts = url.split('/').filter(Boolean);
+    if (pathParts.length <= 1) {
+        // Root level: / or /about
+        return '/';
+    }
+    else {
+        // Collection level: /blog/post-1 -> belongs to /blog
+        return '/' + pathParts.slice(0, -1).join('/');
+    }
+}
+/**
+ * Sorts pages within a single collection.
+ * Primary sort: order field (ascending)
+ * Secondary sort: publishedAt date (descending, newest first)
+ * Tertiary sort: title (ascending)
+ *
+ * @param pages - Pages to sort
+ * @returns Sorted array of pages
+ */
+function sortPagesInCollection(pages) {
+    return pages.sort((a, b) => {
+        // Primary sort by order field
+        const orderA = typeof a.frontMatter.order === 'number' ? a.frontMatter.order : Number.MAX_SAFE_INTEGER;
+        const orderB = typeof b.frontMatter.order === 'number' ? b.frontMatter.order : Number.MAX_SAFE_INTEGER;
+        if (orderA !== orderB) {
+            return orderA - orderB;
+        }
+        // Secondary sort by publishedAt (newest first)
+        if (a.publishedAt && b.publishedAt) {
+            return b.publishedAt.getTime() - a.publishedAt.getTime();
+        }
+        if (a.publishedAt && !b.publishedAt)
+            return -1;
+        if (!a.publishedAt && b.publishedAt)
+            return 1;
+        // Tertiary sort by title
+        const titleA = a.frontMatter.title || basename(a.url);
+        const titleB = b.frontMatter.title || basename(b.url);
+        return titleA.localeCompare(titleB);
+    });
+}
+/**
+ * Sorts navigation nodes by order, then by title
+ */
+function sortNavigationNodes(nodes) {
+    return nodes.sort((a, b) => {
+        // Primary sort by order
+        const orderA = typeof a.order === 'number' ? a.order : Number.MAX_SAFE_INTEGER;
+        const orderB = typeof b.order === 'number' ? b.order : Number.MAX_SAFE_INTEGER;
+        if (orderA !== orderB) {
+            return orderA - orderB;
+        }
+        // Secondary sort by title
+        return a.title.localeCompare(b.title);
+    });
+}
+/**
+ * Creates a navigation node from a single page.
+ *
+ * @param page - Page model to convert
+ * @returns Navigation node
+ */
+function createNavNodeFromPage(page) {
+    const navNode = {
+        title: page.frontMatter.title || basename(page.url) || 'Untitled',
+        url: page.url,
+        path: page.url,
+        isCollection: false,
+    };
+    // Only add order if it's a number
+    if (typeof page.frontMatter.order === 'number') {
+        navNode.order = page.frontMatter.order;
+    }
+    // Only add publishedAt if it exists
+    if (page.publishedAt) {
+        navNode.publishedAt = page.publishedAt;
+    }
+    return navNode;
+}
+/**
+ * Creates a collection navigation node with child pages.
+ *
+ * @param collectionPath - Path of the collection
+ * @param pages - Pages in the collection
+ * @param indexPage - Optional index page for the collection
+ * @returns Navigation node representing the collection
+ */
+function createCollectionNode(collectionPath, pages, indexPage) {
+    const collectionName = basename(collectionPath);
+    // Use index page data if available, otherwise derive from collection
+    const title = indexPage?.frontMatter.title || capitalizeFirst(collectionName);
+    const url = indexPage?.url || collectionPath;
+    const order = indexPage?.frontMatter.order;
+    const publishedAt = indexPage?.publishedAt;
+    const children = sortPagesInCollection(pages).map((page) => createNavNodeFromPage(page));
+    const navNode = {
+        title,
+        url,
+        path: collectionPath,
+        isCollection: true,
+    };
+    // Only add order if it's a number
+    if (typeof order === 'number') {
+        navNode.order = order;
+    }
+    // Only add publishedAt if it exists
+    if (publishedAt) {
+        navNode.publishedAt = publishedAt;
+    }
+    // Only add children if there are any
+    if (children.length > 0) {
+        navNode.children = children;
+    }
+    return navNode;
+}
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str - String to capitalize
+ * @returns Capitalized string
+ */
+function capitalizeFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/dist/core/templates.d.ts

@@ -0,0 +1,5 @@
+import { Eta } from 'eta';
+import type { StatiConfig, PageModel, NavNode } from '../types.js';
+export declare function createTemplateEngine(config: StatiConfig): Eta;
+export declare function renderPage(page: PageModel, body: string, config: StatiConfig, eta: Eta, navigation?: NavNode[], allPages?: PageModel[]): Promise<string>;
+//# sourceMappingURL=templates.d.ts.map

package/dist/core/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAK1B,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAkB,MAAM,aAAa,CAAC;AAgRnF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,GAAG,CAS7D;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,GAAG,EACR,UAAU,CAAC,EAAE,OAAO,EAAE,EACtB,QAAQ,CAAC,EAAE,SAAS,EAAE,GACrB,OAAO,CAAC,MAAM,CAAC,CAgDjB"}

package/dist/core/templates.js

@@ -0,0 +1,307 @@
+import { Eta } from 'eta';
+import { join, dirname, relative, basename } from 'path';
+import fse from 'fs-extra';
+const { pathExists } = fse;
+import glob from 'fast-glob';
+/**
+ * Determines if the given page is an index page for a collection.
+ * An index page is one whose URL matches a directory path that contains other pages.
+ *
+ * @param page - The page to check
+ * @param allPages - All pages in the site
+ * @returns True if the page is a collection index page
+ */
+function isCollectionIndexPage(page, allPages) {
+    // Root index page is always a collection index
+    if (page.url === '/') {
+        return true;
+    }
+    // Check if this page's URL is a directory path that contains other pages
+    const pageUrlAsDir = page.url.endsWith('/') ? page.url : page.url + '/';
+    return allPages.some((otherPage) => otherPage.url !== page.url && otherPage.url.startsWith(pageUrlAsDir));
+}
+/**
+ * Gets the collection path for a given page URL.
+ * For index pages, returns the page's URL. For child pages, returns the parent directory.
+ *
+ * @param pageUrl - The page URL
+ * @returns The collection path
+ */
+function getCollectionPathForPage(pageUrl) {
+    if (pageUrl === '/') {
+        return '/';
+    }
+    const pathParts = pageUrl.split('/').filter(Boolean);
+    if (pathParts.length <= 1) {
+        return '/';
+    }
+    return '/' + pathParts.slice(0, -1).join('/');
+}
+/**
+ * Groups pages by their tags for aggregation purposes.
+ *
+ * @param pages - Pages to group
+ * @returns Object mapping tag names to arrays of pages
+ */
+function groupPagesByTags(pages) {
+    const pagesByTag = {};
+    for (const page of pages) {
+        const tags = page.frontMatter.tags;
+        if (Array.isArray(tags)) {
+            for (const tag of tags) {
+                if (typeof tag === 'string') {
+                    if (!pagesByTag[tag]) {
+                        pagesByTag[tag] = [];
+                    }
+                    pagesByTag[tag].push(page);
+                }
+            }
+        }
+    }
+    return pagesByTag;
+}
+/**
+ * Sorts pages by publishedAt date (most recent first), falling back to alphabetical by title.
+ *
+ * @param pages - Pages to sort
+ * @returns Sorted array of pages
+ */
+function sortPagesByDate(pages) {
+    return pages.sort((a, b) => {
+        // Sort by publishedAt (newest first)
+        if (a.publishedAt && b.publishedAt) {
+            return b.publishedAt.getTime() - a.publishedAt.getTime();
+        }
+        if (a.publishedAt && !b.publishedAt)
+            return -1;
+        if (!a.publishedAt && b.publishedAt)
+            return 1;
+        // Fallback to title
+        const titleA = a.frontMatter.title || basename(a.url) || 'Untitled';
+        const titleB = b.frontMatter.title || basename(b.url) || 'Untitled';
+        return titleA.localeCompare(titleB);
+    });
+}
+/**
+ * Builds collection aggregation data for index pages.
+ * Provides all the data needed for index pages to list and organize their collection's content.
+ *
+ * @param currentPage - The current page being rendered (must be an index page)
+ * @param allPages - All pages in the site
+ * @returns Collection data for template rendering
+ */
+function buildCollectionData(currentPage, allPages) {
+    const collectionPath = currentPage.url === '/' ? '/' : currentPage.url;
+    const collectionName = collectionPath === '/' ? 'Home' : basename(collectionPath);
+    // Find all pages that belong to this collection
+    const collectionPages = allPages.filter((page) => {
+        if (page.url === currentPage.url) {
+            return false; // Don't include the index page itself
+        }
+        if (collectionPath === '/') {
+            // For root collection, include pages that are direct children of root
+            const pageCollectionPath = getCollectionPathForPage(page.url);
+            return pageCollectionPath === '/';
+        }
+        else {
+            // For other collections, include pages that start with the collection path
+            const pageUrlAsDir = collectionPath.endsWith('/') ? collectionPath : collectionPath + '/';
+            return page.url.startsWith(pageUrlAsDir);
+        }
+    });
+    // Find direct children (one level down)
+    const children = collectionPages.filter((page) => {
+        const relativePath = page.url.substring(collectionPath.length);
+        const cleanPath = relativePath.startsWith('/') ? relativePath.substring(1) : relativePath;
+        return !cleanPath.includes('/'); // No further slashes means direct child
+    });
+    // Sort pages by date for recent posts
+    const recentPages = sortPagesByDate([...collectionPages]);
+    // Group by tags
+    const pagesByTag = groupPagesByTags(collectionPages);
+    return {
+        pages: collectionPages,
+        children,
+        recentPages,
+        pagesByTag,
+        metadata: {
+            totalPages: collectionPages.length,
+            hasChildren: children.length > 0,
+            collectionPath,
+            collectionName,
+        },
+    };
+}
+/**
+ * Discovers partials in the hierarchy for a given page path.
+ * Scans all parent directories for folders starting with underscore.
+ *
+ * @param pagePath - The path to the page (relative to srcDir)
+ * @param config - Stati configuration
+ * @returns Object mapping partial names to their file paths
+ */
+async function discoverPartials(pagePath, config) {
+    const srcDir = join(process.cwd(), config.srcDir);
+    const partials = {};
+    // Get the directory of the current page
+    const pageDir = dirname(pagePath);
+    const pathSegments = pageDir === '.' ? [] : pageDir.split('/');
+    // Scan from root to current directory
+    const dirsToScan = [''];
+    for (let i = 0; i < pathSegments.length; i++) {
+        dirsToScan.push(pathSegments.slice(0, i + 1).join('/'));
+    }
+    for (const dir of dirsToScan) {
+        const searchDir = dir ? join(srcDir, dir) : srcDir;
+        // Find all underscore folders in this directory level
+        const underscoreFolders = await glob('_*/', {
+            cwd: searchDir,
+            onlyDirectories: true,
+        });
+        // Scan each underscore folder for .eta files
+        for (const folder of underscoreFolders) {
+            const folderPath = join(searchDir, folder);
+            const etaFiles = await glob('**/*.eta', {
+                cwd: folderPath,
+                absolute: false,
+            });
+            for (const etaFile of etaFiles) {
+                const partialName = basename(etaFile, '.eta');
+                const fullPath = join(folderPath, etaFile);
+                const relativePath = relative(srcDir, fullPath);
+                // Store the relative path from srcDir for Eta to find it
+                partials[partialName] = relativePath;
+            }
+        }
+    }
+    return partials;
+}
+/**
+ * Discovers the appropriate layout file for a given page path.
+ * Implements the hierarchical layout.eta convention by searching
+ * from the page's directory up to the root.
+ *
+ * @param pagePath - The path to the page (relative to srcDir)
+ * @param config - Stati configuration
+ * @param explicitLayout - Layout specified in front matter (takes precedence)
+ * @param isIndexPage - Whether this is an aggregation/index page (enables index.eta lookup)
+ * @returns The layout file path or null if none found
+ */
+async function discoverLayout(pagePath, config, explicitLayout, isIndexPage) {
+    const srcDir = join(process.cwd(), config.srcDir);
+    // If explicit layout is specified, use it
+    if (explicitLayout) {
+        const layoutPath = join(srcDir, `${explicitLayout}.eta`);
+        if (await pathExists(layoutPath)) {
+            return `${explicitLayout}.eta`;
+        }
+    }
+    // Get the directory of the current page
+    const pageDir = dirname(pagePath);
+    const pathSegments = pageDir === '.' ? [] : pageDir.split(/[/\\]/); // Handle both separators
+    // Search for layout.eta from current directory up to root
+    const dirsToSearch = [];
+    // Add current directory if not root
+    if (pathSegments.length > 0) {
+        for (let i = pathSegments.length; i > 0; i--) {
+            dirsToSearch.push(pathSegments.slice(0, i).join('/'));
+        }
+    }
+    // Add root directory
+    dirsToSearch.push('');
+    for (const dir of dirsToSearch) {
+        // For index pages, first check for index.eta in each directory
+        if (isIndexPage) {
+            const indexLayoutPath = dir ? join(srcDir, dir, 'index.eta') : join(srcDir, 'index.eta');
+            if (await pathExists(indexLayoutPath)) {
+                // Return relative path with forward slashes for Eta
+                const relativePath = dir ? `${dir}/index.eta` : 'index.eta';
+                return relativePath.replace(/\\/g, '/'); // Normalize to forward slashes
+            }
+        }
+        // Then check for layout.eta as fallback
+        const layoutPath = dir ? join(srcDir, dir, 'layout.eta') : join(srcDir, 'layout.eta');
+        if (await pathExists(layoutPath)) {
+            // Return relative path with forward slashes for Eta
+            const relativePath = dir ? `${dir}/layout.eta` : 'layout.eta';
+            return relativePath.replace(/\\/g, '/'); // Normalize to forward slashes
+        }
+    }
+    return null;
+}
+export function createTemplateEngine(config) {
+    const templateDir = join(process.cwd(), config.srcDir);
+    const eta = new Eta({
+        views: templateDir,
+        cache: process.env.NODE_ENV === 'production',
+    });
+    return eta;
+}
+export async function renderPage(page, body, config, eta, navigation, allPages) {
+    // Discover partials for this page's directory hierarchy
+    const srcDir = join(process.cwd(), config.srcDir);
+    const relativePath = relative(srcDir, page.sourcePath);
+    const partials = await discoverPartials(relativePath, config);
+    // Build collection data if this is an index page and all pages are provided
+    let collectionData;
+    const isIndexPage = allPages && isCollectionIndexPage(page, allPages);
+    if (isIndexPage) {
+        collectionData = buildCollectionData(page, allPages);
+    }
+    // Discover the appropriate layout using hierarchical layout.eta convention
+    // Pass isIndexPage flag to enable index.eta lookup for aggregation pages
+    const layoutPath = await discoverLayout(relativePath, config, page.frontMatter.layout, isIndexPage);
+    const context = {
+        site: config.site,
+        page: {
+            ...page.frontMatter,
+            path: page.url,
+            content: body,
+        },
+        content: body,
+        navigation: navigation || [],
+        partials, // Add discovered partials to template context
+        collection: collectionData, // Add collection data for index pages
+        // Add custom filters to context
+        ...(config.eta?.filters || {}),
+    };
+    try {
+        if (!layoutPath) {
+            console.warn('No layout template found, using fallback');
+            return createFallbackHtml(page, body);
+        }
+        return await eta.renderAsync(layoutPath, context);
+    }
+    catch (error) {
+        console.error(`Error rendering layout ${layoutPath || 'unknown'}:`, error);
+        return createFallbackHtml(page, body);
+    }
+}
+function createFallbackHtml(page, body) {
+    const title = page.frontMatter.title || 'Untitled';
+    const description = page.frontMatter.description || '';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  ${description ? `<meta name="description" content="${escapeHtml(description)}">` : ''}
+</head>
+<body>
+  <main>
+    ${body}
+  </main>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    const map = {
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+    };
+    return text.replace(/[&<>"']/g, (m) => map[m]);
+}

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview @stati/core - Core engine for Stati static site generator
+ *
+ * @example
+ * ```typescript
+ * import { build, loadConfig, defineConfig } from '@stati/core';
+ *
+ * // Define configuration with TypeScript support
+ * export default defineConfig({
+ *   site: {
+ *     title: 'My Site',
+ *     baseUrl: 'https://example.com',
+ *   },
+ *   // ... other config options
+ * });
+ *
+ * // Load configuration and build site
+ * const config = await loadConfig();
+ * await build({ clean: true });
+ * ```
+ */
+export type { StatiConfig, PageModel, FrontMatter, BuildContext, PageContext, BuildHooks, NavNode, ISGConfig, AgingRule, BuildStats, } from './types.js';
+export type { BuildOptions } from './core/build.js';
+export { build } from './core/build.js';
+export { loadConfig } from './config/loader.js';
+export { invalidate } from './core/invalidate.js';
+import type { StatiConfig } from './types.js';
+/**
+ * Helper function for defining Stati configuration with TypeScript IntelliSense.
+ * Provides type checking and autocompletion for configuration options.
+ *
+ * @param config - The Stati configuration object
+ * @returns The same configuration object with proper typing
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@stati/core';
+ *
+ * export default defineConfig({
+ *   site: {
+ *     title: 'My Blog',
+ *     baseUrl: 'https://myblog.com',
+ *   },
+ *   srcDir: 'content',
+ *   outDir: 'public',
+ *   isg: {
+ *     enabled: true,
+ *     ttlSeconds: 3600,
+ *   },
+ *   hooks: {
+ *     beforeAll: async (ctx) => {
+ *       console.log(`Building ${ctx.pages.length} pages`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(config: StatiConfig): StatiConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACV,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACZ,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,WAAW,CAE7D"}

package/dist/index.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview @stati/core - Core engine for Stati static site generator
+ *
+ * @example
+ * ```typescript
+ * import { build, loadConfig, defineConfig } from '@stati/core';
+ *
+ * // Define configuration with TypeScript support
+ * export default defineConfig({
+ *   site: {
+ *     title: 'My Site',
+ *     baseUrl: 'https://example.com',
+ *   },
+ *   // ... other config options
+ * });
+ *
+ * // Load configuration and build site
+ * const config = await loadConfig();
+ * await build({ clean: true });
+ * ```
+ */
+export { build } from './core/build.js';
+export { loadConfig } from './config/loader.js';
+export { invalidate } from './core/invalidate.js';
+/**
+ * Helper function for defining Stati configuration with TypeScript IntelliSense.
+ * Provides type checking and autocompletion for configuration options.
+ *
+ * @param config - The Stati configuration object
+ * @returns The same configuration object with proper typing
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@stati/core';
+ *
+ * export default defineConfig({
+ *   site: {
+ *     title: 'My Blog',
+ *     baseUrl: 'https://myblog.com',
+ *   },
+ *   srcDir: 'content',
+ *   outDir: 'public',
+ *   isg: {
+ *     enabled: true,
+ *     ttlSeconds: 3600,
+ *   },
+ *   hooks: {
+ *     beforeAll: async (ctx) => {
+ *       console.log(`Building ${ctx.pages.length} pages`);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}