bunki 0.7.1 → 0.8.0

package/README.md

@@ -4,7 +4,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/kahwee/bunki/badge.svg?branch=main)](https://coveralls.io/github/kahwee/bunki?branch=main)
 [![npm version](https://badge.fury.io/js/bunki.svg)](https://badge.fury.io/js/bunki)
 
-Fast static site generator for blogs and documentation built with Bun. Supports Markdown + frontmatter, tags, year-based archives, pagination, RSS feeds, sitemaps, secure HTML sanitization, syntax highlighting, PostCSS pipelines, media uploads (images & videos to S3/R2), incremental uploads with year filtering, and Nunjucks templating.
+Fast static site generator for blogs and documentation built with Bun. Supports Markdown + frontmatter, tags, year-based archives, pagination, RSS feeds, sitemaps, JSON-LD structured data for SEO, secure HTML sanitization, syntax highlighting, PostCSS pipelines, media uploads (images & videos to S3/R2), incremental uploads with year filtering, and Nunjucks templating.
 
 ## Install
 
@@ -122,6 +122,188 @@ Create `templates/styles/main.css`:
 
 CSS is processed automatically during `bunki generate`.
 
+## JSON-LD Structured Data for SEO
+
+Bunki automatically generates [JSON-LD](https://json-ld.org/) structured data markup for enhanced SEO and search engine visibility. JSON-LD (JavaScript Object Notation for Linked Data) is Google's recommended format for structured data.
+
+### What is JSON-LD?
+
+JSON-LD helps search engines better understand your content by providing explicit, structured information about your pages. This can lead to:
+
+- **Rich snippets** in search results (article previews, star ratings, etc.)
+- **Better content indexing** and understanding by search engines
+- **Improved click-through rates** from search results
+- **Knowledge graph integration** with Google, Bing, and other search engines
+
+### Automatic Schema Generation
+
+Bunki automatically generates appropriate schemas for different page types:
+
+#### Blog Posts (BlogPosting Schema)
+
+Every blog post includes comprehensive `BlogPosting` schema with:
+
+- Headline and description
+- Publication and modification dates
+- Author information
+- Publisher details
+- Article keywords (from tags)
+- Word count
+- Featured image (automatically extracted)
+- Language information
+
+Example output in your HTML:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "BlogPosting",
+  "headline": "Getting Started with Bun",
+  "description": "Learn how to get started with Bun, the fast JavaScript runtime.",
+  "url": "https://example.com/2025/getting-started-with-bun/",
+  "datePublished": "2025-01-15T10:30:00.000Z",
+  "dateModified": "2025-01-15T10:30:00.000Z",
+  "author": {
+    "@type": "Person",
+    "name": "John Doe",
+    "email": "john@example.com"
+  },
+  "publisher": {
+    "@type": "Organization",
+    "name": "My Blog",
+    "url": "https://example.com"
+  },
+  "keywords": "bun, javascript, performance",
+  "image": "https://example.com/images/bun-logo.png"
+}
+</script>
+```
+
+#### Homepage (WebSite & Organization Schemas)
+
+The homepage includes dual schemas:
+
+1. **WebSite Schema**: Defines the website entity
+2. **Organization Schema**: Defines the publisher/organization
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "My Blog",
+  "url": "https://example.com",
+  "description": "My thoughts and ideas",
+  "potentialAction": {
+    "@type": "SearchAction",
+    "target": {
+      "@type": "EntryPoint",
+      "urlTemplate": "https://example.com/search?q={search_term_string}"
+    }
+  }
+}
+</script>
+```
+
+#### Breadcrumbs (BreadcrumbList Schema)
+
+All pages include breadcrumb navigation for better site hierarchy understanding:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://example.com"
+    },
+    {
+      "@type": "ListItem",
+      "position": 2,
+      "name": "Getting Started with Bun",
+      "item": "https://example.com/2025/getting-started-with-bun/"
+    }
+  ]
+}
+</script>
+```
+
+### Configuration for SEO
+
+Enhance your JSON-LD output by providing complete author and site information in `bunki.config.ts`:
+
+```typescript
+import { SiteConfig } from "bunki";
+
+export default (): SiteConfig => ({
+  title: "My Blog",
+  description: "My thoughts and ideas on web development",
+  baseUrl: "https://example.com",
+  domain: "example.com",
+
+  // Author information (used in BlogPosting schema)
+  authorName: "John Doe",
+  authorEmail: "john@example.com",
+
+  // RSS/SEO configuration
+  rssLanguage: "en-US", // Language code for content
+  copyright: "Copyright © 2025 My Blog",
+
+  // ... other config
+});
+```
+
+### Testing Your JSON-LD
+
+You can validate your structured data using these tools:
+
+1. **[Google Rich Results Test](https://search.google.com/test/rich-results)** - Test how Google sees your structured data
+2. **[Schema.org Validator](https://validator.schema.org/)** - Validate JSON-LD syntax
+3. **[Structured Data Linter](http://linter.structured-data.org/)** - Check for errors and warnings
+
+### Supported Schema Types
+
+Bunki currently supports these Schema.org types:
+
+- **BlogPosting** - Individual blog posts and articles
+- **WebSite** - Homepage and site-wide metadata
+- **Organization** - Publisher/organization information
+- **Person** - Author information
+- **BreadcrumbList** - Navigation breadcrumbs
+
+### How It Works
+
+JSON-LD generation is completely automatic:
+
+1. **Post Creation**: When you write a post with frontmatter, Bunki extracts metadata
+2. **Site Generation**: During `bunki generate`, appropriate schemas are created
+3. **Template Injection**: JSON-LD scripts are automatically injected into `<head>`
+4. **Image Extraction**: The first image in your post content is automatically used as the featured image
+
+No manual configuration needed - just run `bunki generate` and your site will have complete structured data!
+
+### Best Practices
+
+To maximize SEO benefits:
+
+1. **Use descriptive titles** - Your post title becomes the schema headline
+2. **Write good excerpts** - These become schema descriptions
+3. **Include images** - First image in content is used as featured image
+4. **Tag your posts** - Tags become schema keywords
+5. **Set author info** - Complete `authorName` and `authorEmail` in config
+6. **Use ISO 8601 dates** - Format: `2025-01-15T10:30:00-07:00`
+
+### Further Reading
+
+- [Schema.org Documentation](https://schema.org/)
+- [Google Search Central - Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data)
+- [JSON-LD Official Spec](https://json-ld.org/)
+
 ## Image Management
 
 ### Overview
@@ -568,7 +750,8 @@ dist/
 - **Styling**: Built-in PostCSS support for modern CSS frameworks
 - **Media Management**: Direct S3/R2 uploads for images and MP4 videos with URL mapping
 - **Incremental Uploads**: Year-based filtering (`--min-year`) for large media collections
-- **SEO**: Automatic RSS feeds, sitemaps, meta tags
+- **SEO**: Automatic RSS feeds, sitemaps, meta tags, and JSON-LD structured data
+- **JSON-LD Structured Data**: Automatic Schema.org markup (BlogPosting, WebSite, Organization, BreadcrumbList)
 - **Pagination**: Configurable posts per page
 - **Archives**: Year-based and tag-based organization
 
@@ -606,7 +789,20 @@ bunki/
 
 ## Changelog
 
-### v0.7.0 (Current)
+### v0.8.0 (Current)
+
+- **JSON-LD Structured Data**: Automatic Schema.org markup generation for enhanced SEO
+  - BlogPosting schema for individual blog posts with author, keywords, images
+  - WebSite schema for homepage with search action
+  - Organization schema for publisher information
+  - BreadcrumbList schema for navigation hierarchy
+  - Automatic featured image extraction from post content
+- **Comprehensive SEO**: Complete structured data support following Google best practices
+- **Zero configuration**: JSON-LD automatically generated during site build
+- **Well documented**: Extensive README section with examples and validation tools
+- **Fully tested**: 60+ new tests covering all JSON-LD schema types
+
+### v0.7.0
 
 - **Media uploads**: Added MP4 video support alongside image uploads
 - **Incremental uploads**: Year-based filtering with `--min-year` option

package/dist/cli.js

@@ -32909,6 +32909,152 @@ async function parseMarkdownDirectory(contentDir) {
   }
 }
 
+// src/utils/json-ld.ts
+function generateOrganizationSchema(site) {
+  const organization = {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (site.description) {
+    organization.description = site.description;
+  }
+  return organization;
+}
+function generateBlogPostingSchema(options2) {
+  const { post, site, imageUrl, dateModified } = options2;
+  const postUrl = `${site.baseUrl}${post.url}`;
+  const blogPosting = {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: post.title,
+    description: post.excerpt,
+    url: postUrl,
+    mainEntityOfPage: {
+      "@type": "WebPage",
+      "@id": postUrl
+    },
+    datePublished: post.date,
+    dateModified: dateModified || post.date
+  };
+  if (site.authorName) {
+    blogPosting.author = {
+      "@type": "Person",
+      name: site.authorName,
+      ...site.authorEmail && { email: site.authorEmail }
+    };
+  }
+  blogPosting.publisher = {
+    "@type": "Organization",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (imageUrl) {
+    blogPosting.image = imageUrl;
+  }
+  if (post.tags && post.tags.length > 0) {
+    blogPosting.keywords = post.tags.join(", ");
+  }
+  if (post.tags && post.tags.length > 0) {
+    blogPosting.articleSection = post.tags[0];
+  }
+  if (post.content) {
+    const wordCount = post.content.split(/\s+/).length;
+    blogPosting.wordCount = wordCount;
+  }
+  blogPosting.inLanguage = site.rssLanguage || "en-US";
+  return blogPosting;
+}
+function generateWebSiteSchema(options2) {
+  const { site } = options2;
+  const webSite = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (site.description) {
+    webSite.description = site.description;
+  }
+  webSite.potentialAction = {
+    "@type": "SearchAction",
+    target: {
+      "@type": "EntryPoint",
+      urlTemplate: `${site.baseUrl}/search?q={search_term_string}`
+    },
+    "query-input": "required name=search_term_string"
+  };
+  return webSite;
+}
+function generateBreadcrumbListSchema(options2) {
+  const { site, post, items } = options2;
+  const breadcrumbs = {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: []
+  };
+  if (items && items.length > 0) {
+    breadcrumbs.itemListElement = items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url
+    }));
+    return breadcrumbs;
+  }
+  const homeItem = {
+    "@type": "ListItem",
+    position: 1,
+    name: "Home",
+    item: site.baseUrl
+  };
+  breadcrumbs.itemListElement.push(homeItem);
+  if (post) {
+    breadcrumbs.itemListElement.push({
+      "@type": "ListItem",
+      position: 2,
+      name: post.title,
+      item: `${site.baseUrl}${post.url}`
+    });
+  }
+  return breadcrumbs;
+}
+function toScriptTag(jsonLd) {
+  const json2 = JSON.stringify(jsonLd, null, 2);
+  return `<script type="application/ld+json">
+${json2}
+</script>`;
+}
+function extractFirstImageUrl(html, baseUrl) {
+  const imgMatch = html.match(/<img[^>]+src=["']([^"']+)["']/i);
+  if (!imgMatch || !imgMatch[1]) {
+    return;
+  }
+  const src = imgMatch[1];
+  if (src.startsWith("http://") || src.startsWith("https://")) {
+    return src;
+  }
+  const cleanBaseUrl = baseUrl.replace(/\/$/, "");
+  const cleanSrc = src.startsWith("/") ? src : `/${src}`;
+  return `${cleanBaseUrl}${cleanSrc}`;
+}
+function generatePostPageSchemas(options2) {
+  const schemas = [];
+  schemas.push(generateBlogPostingSchema(options2));
+  schemas.push(generateBreadcrumbListSchema({
+    site: options2.site,
+    post: options2.post
+  }));
+  return schemas;
+}
+function generateHomePageSchemas(options2) {
+  const schemas = [];
+  schemas.push(generateWebSiteSchema(options2));
+  schemas.push(generateOrganizationSchema(options2.site));
+  return schemas;
+}
+
 // src/site-generator.ts
 class SiteGenerator {
   options;
@@ -33094,11 +33240,20 @@ class SiteGenerator {
       const endIndex = startIndex + pageSize;
       const paginatedPosts = this.site.posts.slice(startIndex, endIndex);
       const pagination = this.createPagination(this.site.posts, page, pageSize, "/");
+      let jsonLd = "";
+      if (page === 1) {
+        const schemas = generateHomePageSchemas({
+          site: this.options.config
+        });
+        jsonLd = schemas.map((schema) => toScriptTag(schema)).join(`
+`);
+      }
       const pageHtml = import_nunjucks.default.render("index.njk", {
         site: this.options.config,
         posts: paginatedPosts,
         tags: this.getSortedTags(this.options.config.maxTagsOnHomepage),
-        pagination
+        pagination,
+        jsonLd
       });
       if (page === 1) {
         await Bun.write(path5.join(this.options.outputDir, "index.html"), pageHtml);
@@ -33114,9 +33269,18 @@ class SiteGenerator {
       const postPath = post.url.substring(1);
       const postDir = path5.join(this.options.outputDir, postPath);
       await ensureDir(postDir);
+      const imageUrl = extractFirstImageUrl(post.html, this.options.config.baseUrl);
+      const schemas = generatePostPageSchemas({
+        post,
+        site: this.options.config,
+        imageUrl
+      });
+      const jsonLd = schemas.map((schema) => toScriptTag(schema)).join(`
+`);
       const postHtml = import_nunjucks.default.render("post.njk", {
         site: this.options.config,
-        post
+        post,
+        jsonLd
       });
       await Bun.write(path5.join(postDir, "index.html"), postHtml);
     }

package/dist/index.js

@@ -30856,6 +30856,152 @@ function getDefaultCSSConfig() {
   };
 }
 
+// src/utils/json-ld.ts
+function generateOrganizationSchema(site) {
+  const organization = {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (site.description) {
+    organization.description = site.description;
+  }
+  return organization;
+}
+function generateBlogPostingSchema(options2) {
+  const { post, site, imageUrl, dateModified } = options2;
+  const postUrl = `${site.baseUrl}${post.url}`;
+  const blogPosting = {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: post.title,
+    description: post.excerpt,
+    url: postUrl,
+    mainEntityOfPage: {
+      "@type": "WebPage",
+      "@id": postUrl
+    },
+    datePublished: post.date,
+    dateModified: dateModified || post.date
+  };
+  if (site.authorName) {
+    blogPosting.author = {
+      "@type": "Person",
+      name: site.authorName,
+      ...site.authorEmail && { email: site.authorEmail }
+    };
+  }
+  blogPosting.publisher = {
+    "@type": "Organization",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (imageUrl) {
+    blogPosting.image = imageUrl;
+  }
+  if (post.tags && post.tags.length > 0) {
+    blogPosting.keywords = post.tags.join(", ");
+  }
+  if (post.tags && post.tags.length > 0) {
+    blogPosting.articleSection = post.tags[0];
+  }
+  if (post.content) {
+    const wordCount = post.content.split(/\s+/).length;
+    blogPosting.wordCount = wordCount;
+  }
+  blogPosting.inLanguage = site.rssLanguage || "en-US";
+  return blogPosting;
+}
+function generateWebSiteSchema(options2) {
+  const { site } = options2;
+  const webSite = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: site.title,
+    url: site.baseUrl
+  };
+  if (site.description) {
+    webSite.description = site.description;
+  }
+  webSite.potentialAction = {
+    "@type": "SearchAction",
+    target: {
+      "@type": "EntryPoint",
+      urlTemplate: `${site.baseUrl}/search?q={search_term_string}`
+    },
+    "query-input": "required name=search_term_string"
+  };
+  return webSite;
+}
+function generateBreadcrumbListSchema(options2) {
+  const { site, post, items } = options2;
+  const breadcrumbs = {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: []
+  };
+  if (items && items.length > 0) {
+    breadcrumbs.itemListElement = items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url
+    }));
+    return breadcrumbs;
+  }
+  const homeItem = {
+    "@type": "ListItem",
+    position: 1,
+    name: "Home",
+    item: site.baseUrl
+  };
+  breadcrumbs.itemListElement.push(homeItem);
+  if (post) {
+    breadcrumbs.itemListElement.push({
+      "@type": "ListItem",
+      position: 2,
+      name: post.title,
+      item: `${site.baseUrl}${post.url}`
+    });
+  }
+  return breadcrumbs;
+}
+function toScriptTag(jsonLd) {
+  const json2 = JSON.stringify(jsonLd, null, 2);
+  return `<script type="application/ld+json">
+${json2}
+</script>`;
+}
+function extractFirstImageUrl(html, baseUrl) {
+  const imgMatch = html.match(/<img[^>]+src=["']([^"']+)["']/i);
+  if (!imgMatch || !imgMatch[1]) {
+    return;
+  }
+  const src = imgMatch[1];
+  if (src.startsWith("http://") || src.startsWith("https://")) {
+    return src;
+  }
+  const cleanBaseUrl = baseUrl.replace(/\/$/, "");
+  const cleanSrc = src.startsWith("/") ? src : `/${src}`;
+  return `${cleanBaseUrl}${cleanSrc}`;
+}
+function generatePostPageSchemas(options2) {
+  const schemas = [];
+  schemas.push(generateBlogPostingSchema(options2));
+  schemas.push(generateBreadcrumbListSchema({
+    site: options2.site,
+    post: options2.post
+  }));
+  return schemas;
+}
+function generateHomePageSchemas(options2) {
+  const schemas = [];
+  schemas.push(generateWebSiteSchema(options2));
+  schemas.push(generateOrganizationSchema(options2.site));
+  return schemas;
+}
+
 // src/site-generator.ts
 class SiteGenerator {
   options;
@@ -31041,11 +31187,20 @@ class SiteGenerator {
       const endIndex = startIndex + pageSize;
       const paginatedPosts = this.site.posts.slice(startIndex, endIndex);
       const pagination = this.createPagination(this.site.posts, page, pageSize, "/");
+      let jsonLd = "";
+      if (page === 1) {
+        const schemas = generateHomePageSchemas({
+          site: this.options.config
+        });
+        jsonLd = schemas.map((schema) => toScriptTag(schema)).join(`
+`);
+      }
       const pageHtml = import_nunjucks.default.render("index.njk", {
         site: this.options.config,
         posts: paginatedPosts,
         tags: this.getSortedTags(this.options.config.maxTagsOnHomepage),
-        pagination
+        pagination,
+        jsonLd
       });
       if (page === 1) {
         await Bun.write(path5.join(this.options.outputDir, "index.html"), pageHtml);
@@ -31061,9 +31216,18 @@ class SiteGenerator {
       const postPath = post.url.substring(1);
       const postDir = path5.join(this.options.outputDir, postPath);
       await ensureDir(postDir);
+      const imageUrl = extractFirstImageUrl(post.html, this.options.config.baseUrl);
+      const schemas = generatePostPageSchemas({
+        post,
+        site: this.options.config,
+        imageUrl
+      });
+      const jsonLd = schemas.map((schema) => toScriptTag(schema)).join(`
+`);
       const postHtml = import_nunjucks.default.render("post.njk", {
         site: this.options.config,
-        post
+        post,
+        jsonLd
       });
       await Bun.write(path5.join(postDir, "index.html"), postHtml);
     }

package/dist/utils/json-ld.d.ts

@@ -0,0 +1,205 @@
+/**
+ * JSON-LD (JavaScript Object Notation for Linked Data) utility functions
+ * for generating structured data markup for SEO optimization.
+ *
+ * This module provides functions to generate Schema.org structured data
+ * in JSON-LD format, which helps search engines better understand your content.
+ *
+ * Supported schema types:
+ * - BlogPosting: For individual blog posts/articles
+ * - WebSite: For the homepage/website metadata
+ * - BreadcrumbList: For navigation breadcrumbs
+ * - Organization: For publisher/organization information
+ * - Person: For author information
+ *
+ * @see https://schema.org/
+ * @see https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
+ */
+import type { Post, SiteConfig } from "../types.js";
+/**
+ * Base Schema.org Thing type
+ */
+interface SchemaOrgThing {
+    "@context": "https://schema.org";
+    "@type": string;
+    [key: string]: any;
+}
+/**
+ * Options for generating BlogPosting JSON-LD
+ */
+export interface BlogPostingOptions {
+    /** The post object */
+    post: Post;
+    /** Site configuration */
+    site: SiteConfig;
+    /** Optional image URL for the post (first image extracted from content) */
+    imageUrl?: string;
+    /** Optional date modified (defaults to date published) */
+    dateModified?: string;
+}
+/**
+ * Options for generating WebSite JSON-LD
+ */
+export interface WebSiteOptions {
+    /** Site configuration */
+    site: SiteConfig;
+}
+/**
+ * Options for generating BreadcrumbList JSON-LD
+ */
+export interface BreadcrumbListOptions {
+    /** Site configuration */
+    site: SiteConfig;
+    /** Current post (optional, for post pages) */
+    post?: Post;
+    /** Custom breadcrumb items */
+    items?: Array<{
+        name: string;
+        url: string;
+    }>;
+}
+/**
+ * Generates a Person schema for author information
+ *
+ * @param name - Author's name
+ * @param email - Author's email (optional)
+ * @returns Person schema object
+ *
+ * @example
+ * const author = generatePersonSchema("John Doe", "john@example.com");
+ * // Returns: { "@type": "Person", "name": "John Doe", "email": "john@example.com" }
+ */
+export declare function generatePersonSchema(name: string, email?: string): SchemaOrgThing;
+/**
+ * Generates an Organization schema for publisher information
+ *
+ * @param site - Site configuration
+ * @returns Organization schema object
+ *
+ * @example
+ * const org = generateOrganizationSchema({ title: "My Blog", baseUrl: "https://example.com" });
+ * // Returns: { "@type": "Organization", "name": "My Blog", "url": "https://example.com" }
+ */
+export declare function generateOrganizationSchema(site: SiteConfig): SchemaOrgThing;
+/**
+ * Generates BlogPosting structured data for a blog post
+ *
+ * This is the primary schema for individual blog posts/articles.
+ * It provides search engines with detailed information about the post
+ * including title, author, publication date, content, and more.
+ *
+ * @param options - BlogPosting generation options
+ * @returns BlogPosting schema as JSON-LD object
+ *
+ * @example
+ * const jsonLd = generateBlogPostingSchema({
+ *   post: { title: "Hello World", date: "2025-01-15T10:00:00Z", ... },
+ *   site: { title: "My Blog", baseUrl: "https://example.com", ... }
+ * });
+ *
+ * @see https://schema.org/BlogPosting
+ */
+export declare function generateBlogPostingSchema(options: BlogPostingOptions): SchemaOrgThing;
+/**
+ * Generates WebSite structured data for the homepage
+ *
+ * This schema provides search engines with information about the website
+ * itself, including name, description, and URL.
+ *
+ * @param options - WebSite generation options
+ * @returns WebSite schema as JSON-LD object
+ *
+ * @example
+ * const jsonLd = generateWebSiteSchema({
+ *   site: { title: "My Blog", baseUrl: "https://example.com", description: "..." }
+ * });
+ *
+ * @see https://schema.org/WebSite
+ */
+export declare function generateWebSiteSchema(options: WebSiteOptions): SchemaOrgThing;
+/**
+ * Generates BreadcrumbList structured data for navigation
+ *
+ * Breadcrumbs help search engines understand the site's hierarchy
+ * and can appear in search results.
+ *
+ * @param options - BreadcrumbList generation options
+ * @returns BreadcrumbList schema as JSON-LD object
+ *
+ * @example
+ * // For a blog post
+ * const jsonLd = generateBreadcrumbListSchema({
+ *   site: { title: "My Blog", baseUrl: "https://example.com" },
+ *   post: { title: "Hello World", url: "/2025/hello-world/" }
+ * });
+ *
+ * @see https://schema.org/BreadcrumbList
+ */
+export declare function generateBreadcrumbListSchema(options: BreadcrumbListOptions): SchemaOrgThing;
+/**
+ * Converts a JSON-LD object to an HTML script tag string
+ *
+ * This helper function serializes the JSON-LD object and wraps it
+ * in a script tag for inclusion in HTML templates.
+ *
+ * @param jsonLd - The JSON-LD object to convert
+ * @returns HTML script tag string
+ *
+ * @example
+ * const schema = generateBlogPostingSchema({ ... });
+ * const scriptTag = toScriptTag(schema);
+ * // Returns: '<script type="application/ld+json">{"@context":"https://schema.org",...}</script>'
+ */
+export declare function toScriptTag(jsonLd: SchemaOrgThing): string;
+/**
+ * Extracts the first image URL from HTML content
+ *
+ * Searches for the first <img> tag in HTML content and returns its src attribute.
+ * This is useful for automatically finding a representative image for BlogPosting schema.
+ *
+ * @param html - HTML content to search
+ * @param baseUrl - Base URL to prepend to relative image URLs
+ * @returns Full image URL or undefined if no image found
+ *
+ * @example
+ * const imageUrl = extractFirstImageUrl(
+ *   '<p>Text</p><img src="/img/photo.jpg" alt="Photo">',
+ *   'https://example.com'
+ * );
+ * // Returns: 'https://example.com/img/photo.jpg'
+ */
+export declare function extractFirstImageUrl(html: string, baseUrl: string): string | undefined;
+/**
+ * Generates multiple JSON-LD schemas for a blog post page
+ *
+ * This is a convenience function that generates all relevant schemas
+ * for a typical blog post page: BlogPosting, BreadcrumbList, and Organization.
+ *
+ * @param options - BlogPosting generation options
+ * @returns Array of JSON-LD schemas
+ *
+ * @example
+ * const schemas = generatePostPageSchemas({
+ *   post: { ... },
+ *   site: { ... }
+ * });
+ * // Returns: [BlogPosting, BreadcrumbList]
+ */
+export declare function generatePostPageSchemas(options: BlogPostingOptions): SchemaOrgThing[];
+/**
+ * Generates multiple JSON-LD schemas for the homepage
+ *
+ * This is a convenience function that generates all relevant schemas
+ * for the homepage: WebSite and Organization.
+ *
+ * @param options - WebSite generation options
+ * @returns Array of JSON-LD schemas
+ *
+ * @example
+ * const schemas = generateHomePageSchemas({
+ *   site: { title: "My Blog", baseUrl: "https://example.com", ... }
+ * });
+ * // Returns: [WebSite, Organization]
+ */
+export declare function generateHomePageSchemas(options: WebSiteOptions): SchemaOrgThing[];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunki",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "An opinionated static site generator built with Bun featuring PostCSS integration and modern web development workflows",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -63,7 +63,7 @@
     "@types/nunjucks": "^3.2.6",
     "@types/sanitize-html": "^2.16.0",
     "autoprefixer": "^10.4.21",
-    "bun-types": "^1.3.1",
+    "bun-types": "^1.3.2",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.6",
     "prettier": "^3.6.2",
@@ -84,7 +84,7 @@
     "README.md"
   ],
   "engines": {
-    "bun": ">=1.3.0",
+    "bun": ">=1.3.2",
     "node": ">=18.0.0"
   },
   "engineStrict": true,