miki-template 2.3.1 → 2.3.3

package/docs/api/render.md

@@ -1,184 +0,0 @@
-# render()
-
-
-
-Render a template string or file partial.
-
-
-
-## Signature
-
-
-
-```javascript
-
-render(templateStr, contextObj = {}, options = {})
-
-```
-
-
-
-## Parameters
-
-
-
-| Parameter | Type | Description |
-
-|-----------|------|-------------|
-
-| `templateStr` | `string` | Template string or file path with `#partial` suffix |
-
-| `contextObj` | `object` | Variables to inject into the template |
-
-| `options` | `object` | Options including `views` directories and custom settings |
-
-
-
-## Returns
-
-
-
-`string` — The rendered HTML.
-
-
-
-## Examples
-
-
-
-### Render a template string
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { render } = require('miki-template');
-
-
-
-    const html = render('Hello {{ name }}!', { name: 'World' });
-
-    // Output: Hello World!
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { render } from 'miki-template';
-
-
-
-    const html = render('Hello {{ name }}!', { name: 'World' });
-
-    // Output: Hello World!
-
-    ```
-
-
-
-### Render a partial from file
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { render } = require('miki-template');
-
-
-
-    const html = render('home#card', { title: 'Hello' }, { views: './views' });
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { render } from 'miki-template';
-
-
-
-    const html = render('home#card', { title: 'Hello' }, { views: './views' });
-
-    ```
-
-
-
-### Render with options
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { render } = require('miki-template');
-
-
-
-    const html = render(template, context, {
-
-      views: ['./views', './app/templates'],
-
-      staticUrl: '/static',
-
-      urlHelper: (name, ...args) => '/' + name + '/' + args.join('/')
-
-    });
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { render } from 'miki-template';
-
-
-
-    const html = render(template, context, {
-
-      views: ['./views', './app/templates'],
-
-      staticUrl: '/static',
-
-      urlHelper: (name, ...args) => '/' + name + '/' + args.join('/')
-
-    });
-
-    ```
-
-
-
-## Related
-
-
-
-- [compile()](./compile.md)
-
-- [asyncRender()](./async-render.md)
-

package/docs/api/security.md

@@ -1,290 +0,0 @@
-# Security API
-
-
-
-## markSafe
-
-
-
-Mark a string as safe (bypass auto-escaping).
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { markSafe } = require('miki-template');
-
-
-
-    const html = markSafe('<b>ok</b>');
-
-    // Will not be escaped
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { markSafe } from 'miki-template';
-
-
-
-    const html = markSafe('<b>ok</b>');
-
-    ```
-
-
-
-## isSafe
-
-
-
-Check if a value is marked safe.
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { isSafe } = require('miki-template');
-
-
-
-    if (isSafe(value)) {
-
-      // value is marked safe
-
-    }
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { isSafe } from 'miki-template';
-
-
-
-    if (isSafe(value)) {
-
-      // value is marked safe
-
-    }
-
-    ```
-
-
-
-## escapeHtml
-
-
-
-Escape HTML special characters (`&`, `<`, `>`, `"`, `'`, `` ` ``).
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { escapeHtml } = require('miki-template');
-
-
-
-    const escaped = escapeHtml('<script>');
-
-    // Output: &lt;script&gt;
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { escapeHtml } from 'miki-template';
-
-
-
-    const escaped = escapeHtml('<script>');
-
-    ```
-
-
-
-### Force-Escape SafeString
-
-
-
-Pass `true` as the second argument to force-escape a `SafeString` (matching Django's `|escape` filter behavior):
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { escapeHtml, SafeString } = require('miki-template');
-
-
-
-    const safe = new SafeString('<b>bold</b>');
-
-    const forced = escapeHtml(safe, true);
-
-    // Output: &lt;b&gt;bold&lt;/b&gt;
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { escapeHtml, SafeString } from 'miki-template';
-
-
-
-    const safe = new SafeString('<b>bold</b>');
-
-    const forced = escapeHtml(safe, true);
-
-    ```
-
-
-
-## stripExpressContext
-
-
-
-Strip Express-specific framework keys (`_`, `settings`, `cache`) from a context object.
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { stripExpressContext } = require('miki-template');
-
-
-
-    const cleanCtx = stripExpressContext(expressOptions);
-
-    // Removes: _locals, settings, cache, and other _ prefixed keys
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { stripExpressContext } from 'miki-template';
-
-
-
-    const cleanCtx = stripExpressContext(expressOptions);
-
-    ```
-
-
-
-## SafeString Class
-
-
-
-Create a SafeString instance directly.
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const { SafeString } = require('miki-template');
-
-
-
-    const safe = new SafeString('<b>ok</b>');
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import { SafeString } from 'miki-template';
-
-
-
-    const safe = new SafeString('<b>ok</b>');
-
-    ```
-
-
-
-## Path Traversal Protection
-
-
-
-The `extends` and `include` tags validate that resolved template paths stay within configured views directories. Attempting to traverse outside throws an error:
-
-
-
-```html
-
-{% extends "../../etc/passwd" %}  <!-- throws -->
-
-{% include "../../secrets" %}     <!-- throws -->
-
-```
-
-
-
-## Next Steps
-
-
-
-- [Security Guide](../guide/security.md)
-
-- [API Reference](../index.md)
-

package/docs/api/setup-express.md

@@ -1,152 +0,0 @@
-# setupExpress()
-
-
-
-One-line Express integration that wires the view engine, views directory, and partial responses.
-
-
-
-## Signature
-
-
-
-```javascript
-
-setupExpress(app, options = {})
-
-```
-
-
-
-## Options
-
-
-
-| Option | Type | Description |
-
-|--------|------|-------------|
-
-| `extension` | `string` | View file extension, default `'html'` |
-
-| `views` | `string\|string[]` | Views directory path(s) |
-
-| `async` | `boolean` | Use async engine (`__expressAsync`) for Express 5+ |
-
-
-
-## What It Does
-
-
-
-- Calls `app.engine()` with the miki view engine.
-
-- Sets `app.set('view engine', extension)` if not already set.
-
-- Sets `app.set('views', views)` if `options.views` is provided.
-
-- Expands `views` to include nested template directories (app-style `templates/` folders).
-
-- Patches `res.render` to support `view#partial` syntax for HTMX responses.
-
-
-
-## Example
-
-
-
-=== "CommonJS"
-
-
-
-    ```javascript
-
-    const express = require('express');
-
-    const miki = require('miki-template');
-
-
-
-    const app = express();
-
-    miki.setupExpress(app, { extension: 'html', views: './views' });
-
-
-
-    app.get('/', (req, res) => res.render('home', { user: req.user }));
-
-    app.get('/card/:id', (req, res) =>
-
-      res.render(`home#card`, { title: 'Hello' })
-
-    );
-
-
-
-    app.listen(3000);
-
-    ```
-
-
-
-=== "ES Modules"
-
-
-
-    ```javascript
-
-    import express from 'express';
-
-    import miki from 'miki-template';
-
-
-
-    const app = express();
-
-    miki.setupExpress(app, { extension: 'html', views: './views' });
-
-
-
-    app.get('/', (req, res) => res.render('home', { user: req.user }));
-
-    app.get('/card/:id', (req, res) =>
-
-      res.render(`home#card`, { title: 'Hello' })
-
-    );
-
-
-
-    app.listen(3000);
-
-    ```
-
-
-
-## Partial Responses
-
-
-
-`setupExpress()` patches `res.render` so that any view name containing `#` renders only the named partial:
-
-
-
-```javascript
-
-// Renders only the "card" partialdef from home.html
-
-res.render('home#card', { title: 'Hello' });
-
-```
-
-
-
-This is ideal for HTMX where you only need to update a portion of the page.
-
-
-
-## Related
-
-
-
-- [Integrations: Express](../integrations/express.md)
-