bunki 0.18.5 → 0.19.0

package/README.md

@@ -391,6 +391,77 @@ To maximize SEO benefits:
 - [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/)
 
+## Template Fragments
+
+Bunki ships reusable Nunjucks macros called **fragments**. They're registered as a second template search path alongside your site's `templates/` directory, so you can import them from any template without any configuration.
+
+### Available fragments
+
+| File | Macros | Purpose |
+|------|--------|---------|
+| `og-image.njk` | `og_image(post, site)`, `twitter_image(post, site)` | Open Graph and Twitter Card image meta tags |
+| `json-ld.njk` | `blog_posting_schema(post, site)`, `local_business_schema(post, site)` | Schema.org structured data scripts |
+| `share-buttons.njk` | `share_buttons(post, site)` | X / Facebook / LinkedIn / Email share button row (Tailwind) |
+| `pagination.njk` | `pagination_nav(pagination)` | Previous / Next pagination nav (Tailwind) |
+
+### Using fragments
+
+Import macros at the top of any template with `{% from %}`:
+
+```nunjucks
+{# post.njk #}
+{% from "og-image.njk" import og_image, twitter_image %}
+{% from "json-ld.njk" import blog_posting_schema %}
+
+{% block og_image %}{{ og_image(post, site) }}{% endblock %}
+{% block twitter_image %}{{ twitter_image(post, site) }}{% endblock %}
+
+{% block head %}
+  {{ blog_posting_schema(post, site) }}
+{% endblock %}
+```
+
+```nunjucks
+{# index.njk, tag.njk, archive.njk #}
+{% from "pagination.njk" import pagination_nav %}
+
+{{ pagination_nav(pagination) }}
+```
+
+The default templates generated by `bunki init` use `og-image.njk` and `json-ld.njk` automatically. The `share-buttons.njk` and `pagination.njk` fragments use Tailwind CSS utility classes and are intended for sites that include Tailwind in their build.
+
+### Writing your own fragments
+
+Fragments are standard Nunjucks macro files. You can place your own in your site's `templates/` directory and import them the same way — site templates take priority over built-in fragments if names collide.
+
+```nunjucks
+{# templates/my-macros.njk #}
+{% macro breadcrumbs(post, site) %}
+  <nav aria-label="Breadcrumb">
+    <a href="/">Home</a> /
+    <span>{{ post.title }}</span>
+  </nav>
+{% endmacro %}
+```
+
+```nunjucks
+{# templates/post.njk #}
+{% from "my-macros.njk" import breadcrumbs %}
+{{ breadcrumbs(post, site) }}
+```
+
+### Template variables reference
+
+| Variable | Available in | Description |
+|----------|-------------|-------------|
+| `site` | All templates | Site config: `title`, `description`, `baseUrl`, `author` |
+| `post` | `post.njk` | Post data: `title`, `excerpt`, `html`, `url`, `date`, `tags`, `tagSlugs`, `image`, `business` |
+| `posts` | `index.njk`, `archive.njk` | Array of post objects |
+| `pagination` | `index.njk`, `tag.njk`, `archive.njk` | `currentPage`, `totalPages`, `hasPrevPage`, `hasNextPage`, `prevPage`, `nextPage`, `pagePath` |
+| `tag` | `tag.njk` | Tag object: `name`, `slug`, `description`, `posts` |
+| `tags` | All templates | Array of tag objects: `name`, `slug`, `count`, `description` |
+| `year` | `archive.njk` | Year string, e.g. `"2025"` |
+
 ## Image Management
 
 ### Overview
@@ -1195,7 +1266,18 @@ bunki/
 
 ## Changelog
 
-### v0.18.1 (Current)
+### v0.19.0 (Current)
+
+- **Template Fragments**: Built-in reusable Nunjucks macros available in all site templates
+  - `og-image.njk` — `og_image(post, site)` and `twitter_image(post, site)` for Open Graph / Twitter Card image tags
+  - `json-ld.njk` — `blog_posting_schema(post, site)` and `local_business_schema(post, site)` for Schema.org structured data
+  - `share-buttons.njk` — `share_buttons(post, site)` for X / Facebook / LinkedIn / Email share buttons (Tailwind)
+  - `pagination.njk` — `pagination_nav(pagination)` for previous/next navigation (Tailwind)
+  - Fragments are registered as a second Nunjucks search path; site templates take priority over built-in fragments
+- **Improved init templates**: `bunki init` now generates templates with canonical URLs, Open Graph meta tags, Twitter Cards, RSS feed link, share buttons, and JSON-LD structured data out of the box
+- **Template variables reference**: Added documentation for all variables available in each template type
+
+### v0.18.1
 
 - **Page Generation Optimization**: Cache JSON-LD schemas and metadata during initialization
   - Eliminates 910 redundant operations per build (455 posts × 2)