@zpress/templates 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Create a template registry, optionally pre-loaded with the given templates.
+ *
+ * When called with no arguments, the registry is populated with all built-in
+ * templates. Pass an explicit array to provide a custom set, or an empty array
+ * to start from scratch.
+ *
+ * @example
+ * ```ts
+ * import { createRegistry } from '@zpress/templates'
+ *
+ * // Use built-in templates as-is
+ * const registry = createRegistry()
+ * const guide = registry.get('guide')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Start with an empty registry
+ * const registry = createRegistry([])
+ *   .add(defineTemplate({
+ *     type: 'adr',
+ *     label: 'ADR',
+ *     hint: 'Architecture decision record',
+ *     body: '# {{title}}\n\n## Context\n\n## Decision\n\n## Consequences\n',
+ *   }))
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Extend a built-in template
+ * const registry = createRegistry()
+ *   .extend('guide', {
+ *     body: (base) => base + '\n## Internal Notes\n',
+ *   })
+ * ```
+ *
+ * @param templates - Optional array of templates to seed the registry with.
+ *   Defaults to built-in templates when omitted.
+ * @returns Template registry
+ */
+export declare function createRegistry(templates?: readonly Template[]): TemplateRegistry;
+
+/**
+ * Define a new documentation template.
+ *
+ * @example
+ * ```ts
+ * import { defineTemplate, createRegistry } from '@zpress/templates'
+ *
+ * const adr = defineTemplate({
+ *   type: 'adr',
+ *   label: 'ADR',
+ *   hint: 'Architecture decision record',
+ *   body: '# {{title}}\n\n## Context\n\n## Decision\n\n## Consequences\n',
+ * })
+ *
+ * const registry = createRegistry().add(adr)
+ * ```
+ *
+ * @param options - Template definition including type, label, hint, and body
+ * @returns A new template object
+ */
+export declare function defineTemplate(options: Template): Template;
+
+/**
+ * Options for extending an existing template.
+ */
+export declare interface ExtendTemplateOptions {
+    readonly label?: string;
+    readonly hint?: string;
+    readonly body?: string | ((base: string) => string);
+}
+
+/**
+ * Get all built-in documentation templates keyed by type.
+ *
+ * @returns Record of all built-in templates keyed by type
+ */
+export declare function getBuiltInTemplates(): Record<TemplateType, Template>;
+
+/**
+ * Render a template by replacing all `{{key}}` placeholders with
+ * the corresponding values from the variables map.
+ *
+ * @example
+ * ```ts
+ * const output = render(template, { title: 'Authentication' })
+ * ```
+ *
+ * @param template - The template whose body contains `{{key}}` placeholders
+ * @param variables - Key/value map used to replace each placeholder
+ * @returns The rendered string with all placeholders substituted
+ */
+export declare function render(template: Template, variables: TemplateVariables): string;
+
+/**
+ * A documentation template definition.
+ */
+export declare interface Template {
+    readonly type: string;
+    readonly label: string;
+    readonly hint: string;
+    readonly body: string;
+}
+
+/**
+ * Built-in template type identifiers.
+ */
+export declare const TEMPLATE_TYPES: readonly ["tutorial", "guide", "quickstart", "explanation", "reference", "standard", "troubleshooting", "runbook"];
+
+/**
+ * An immutable registry of templates.
+ */
+export declare interface TemplateRegistry {
+    readonly templates: ReadonlyMap<string, Template>;
+    readonly get: (type: string) => Template | undefined;
+    readonly has: (type: string) => boolean;
+    readonly list: () => readonly Template[];
+    readonly types: () => readonly string[];
+    readonly add: (template: Template) => TemplateRegistry;
+    readonly extend: (type: string, options: ExtendTemplateOptions) => TemplateRegistry;
+    readonly merge: (other: TemplateRegistry) => TemplateRegistry;
+}
+
+/**
+ * A built-in template type identifier.
+ */
+export declare type TemplateType = (typeof TEMPLATE_TYPES)[number];
+
+/**
+ * Variables available for template rendering.
+ * `title` is always required; additional custom variables are allowed.
+ */
+export declare interface TemplateVariables {
+    readonly title: string;
+    readonly [key: string]: string;
+}
+
+/**
+ * Convert a title string to a kebab-case filename slug.
+ *
+ * @example
+ * ```ts
+ * toSlug('Deploy to Vercel') // 'deploy-to-vercel'
+ * ```
+ *
+ * @param title - The human-readable title to convert
+ * @returns A kebab-case slug suitable for use as a filename
+ */
+export declare function toSlug(title: string): string;
+
+export { }

package/dist/index.mjs

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isFunction, kebabCase } from "es-toolkit";
+const TEMPLATE_TYPES = [
+    'tutorial',
+    'guide',
+    'quickstart',
+    'explanation',
+    'reference',
+    'standard',
+    'troubleshooting',
+    'runbook'
+];
+const BUILT_IN_TEMPLATE_RECORD = {
+    tutorial: {
+        type: 'tutorial',
+        label: 'Tutorial',
+        hint: 'Guided learning experience',
+        body: readTemplate('tutorial.liquid')
+    },
+    guide: {
+        type: 'guide',
+        label: 'Guide',
+        hint: 'Step-by-step task instructions',
+        body: readTemplate('guide.liquid')
+    },
+    quickstart: {
+        type: 'quickstart',
+        label: 'Quickstart',
+        hint: 'Fast-track to working result',
+        body: readTemplate('quickstart.liquid')
+    },
+    explanation: {
+        type: 'explanation',
+        label: 'Explanation',
+        hint: 'Conceptual background',
+        body: readTemplate('explanation.liquid')
+    },
+    reference: {
+        type: 'reference',
+        label: 'Reference',
+        hint: "Technical descriptions",
+        body: readTemplate('reference.liquid')
+    },
+    standard: {
+        type: 'standard',
+        label: 'Standard',
+        hint: 'Rules and conventions',
+        body: readTemplate('standard.liquid')
+    },
+    troubleshooting: {
+        type: 'troubleshooting',
+        label: 'Troubleshooting',
+        hint: 'Common problems and fixes',
+        body: readTemplate('troubleshooting.liquid')
+    },
+    runbook: {
+        type: 'runbook',
+        label: 'Runbook',
+        hint: 'Operational procedures',
+        body: readTemplate('runbook.liquid')
+    }
+};
+function getBuiltInTemplates() {
+    return BUILT_IN_TEMPLATE_RECORD;
+}
+function readTemplate(filename) {
+    return readFileSync(join(import.meta.dirname, '..', 'templates', filename), 'utf8');
+}
+function createRegistry(templates) {
+    const entries = resolveEntries(templates);
+    return createFromMap(entries);
+}
+function resolveEntries(templates) {
+    if (void 0 === templates) return new Map(Object.entries(getBuiltInTemplates()));
+    return new Map(templates.map((t)=>[
+            t.type,
+            t
+        ]));
+}
+function resolveBody(base, override) {
+    if (void 0 === override) return base;
+    if (isFunction(override)) return override(base);
+    return override;
+}
+function applyExtension(base, options) {
+    return {
+        type: base.type,
+        label: options.label ?? base.label,
+        hint: options.hint ?? base.hint,
+        body: resolveBody(base.body, options.body)
+    };
+}
+function createFromMap(templates) {
+    return {
+        templates,
+        get: (type)=>templates.get(type),
+        has: (type)=>templates.has(type),
+        list: ()=>[
+                ...templates.values()
+            ],
+        types: ()=>[
+                ...templates.keys()
+            ],
+        add: (template)=>createFromMap(new Map([
+                ...templates,
+                [
+                    template.type,
+                    template
+                ]
+            ])),
+        extend: (type, options)=>{
+            const base = templates.get(type);
+            if (!base) return createFromMap(templates);
+            const extended = applyExtension(base, options);
+            return createFromMap(new Map([
+                ...templates,
+                [
+                    type,
+                    extended
+                ]
+            ]));
+        },
+        merge: (other)=>createFromMap(new Map([
+                ...templates,
+                ...other.templates
+            ]))
+    };
+}
+function defineTemplate(options) {
+    return {
+        ...options
+    };
+}
+function render(template, variables) {
+    return Object.entries(variables).reduce((result, [key, value])=>result.replaceAll(`{{${key}}}`, value), template.body);
+}
+function toSlug(title) {
+    return kebabCase(title);
+}
+export { TEMPLATE_TYPES, createRegistry, defineTemplate, getBuiltInTemplates, render, toSlug };

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zpress/templates",
+  "version": "0.1.0",
+  "description": "Documentation templates SDK for zpress — use built-in templates, extend them, or register custom ones",
+  "keywords": [
+    "docs",
+    "documentation",
+    "scaffold",
+    "templates",
+    "zpress"
+  ],
+  "homepage": "https://github.com/joggrdocs/zpress/tree/main/packages/templates#readme",
+  "bugs": "https://github.com/joggrdocs/zpress/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joggrdocs/zpress.git",
+    "directory": "packages/templates"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch --no-clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "es-toolkit": "catalog:"
+  },
+  "devDependencies": {
+    "@rslib/core": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/templates/explanation.liquid

@@ -0,0 +1,34 @@
+# {{title}}
+
+<!-- One sentence: what this topic is and why it matters. -->
+
+## Architecture
+
+<!-- Optional: include a diagram if it clarifies the design. -->
+
+## Key Concepts
+
+### Concept 1
+
+Explanation with minimal example.
+
+### Concept 2
+
+Explanation with minimal example.
+
+## Usage
+
+### Basic Usage
+
+```ts
+// Focused example
+```
+
+### Advanced Usage
+
+<!-- Optional: more complex example. -->
+
+## References
+
+- [Related Guide](../guides/related.md)
+- [Related Reference](../reference/related.md)

package/templates/guide.liquid

@@ -0,0 +1,58 @@
+# {{title}}
+
+<!-- One sentence: what this guide accomplishes. -->
+
+## Prerequisites
+
+- Requirement 1
+- Requirement 2
+
+## Steps
+
+### 1. First Step
+
+Brief explanation.
+
+```bash
+command here
+```
+
+### 2. Second Step
+
+Brief explanation.
+
+```ts
+// Code example if needed
+```
+
+### 3. Third Step
+
+<!-- Continue as needed. -->
+
+## Verification
+
+How to verify the task completed successfully:
+
+```bash
+verification-command
+```
+
+Expected output or behavior.
+
+## Troubleshooting
+
+<!-- Optional: include if there are known failure modes. -->
+
+### Common Issue Name
+
+**Symptom:** Brief description of problem.
+
+**Fix:**
+
+```bash
+solution-command
+```
+
+## References
+
+- [Related Doc](../path/to/doc.md)

package/templates/quickstart.liquid

@@ -0,0 +1,51 @@
+# Get Started with {{title}}
+
+<!-- One sentence: what the reader will have working by the end. -->
+
+## What You Will Build
+
+A working implementation that does something useful.
+
+## Prerequisites
+
+- Prerequisite 1
+- Prerequisite 2
+
+## Steps
+
+### 1. First Step
+
+```bash
+command here
+```
+
+### 2. Second Step
+
+```bash
+command here
+```
+
+### 3. Third Step
+
+```ts
+// Code example if needed
+```
+
+<!-- Max 5 steps. No explanations. Fastest path. -->
+
+## Result
+
+```bash
+verification-command
+```
+
+You should see:
+
+```
+expected output
+```
+
+## Next Steps
+
+- [Full tutorial](../tutorials/related.md) — learn the concepts
+- [Guide title](../guides/related.md) — apply to a real task

package/templates/reference.liquid

@@ -0,0 +1,20 @@
+# {{title}}
+
+<!-- One sentence: what this reference covers. -->
+
+## Options
+
+| Option    | Type      | Default     | Description      |
+| --------- | --------- | ----------- | ---------------- |
+| `option1` | `string`  | `"default"` | What it does     |
+| `option2` | `boolean` | `false`     | What it controls |
+
+## Examples
+
+```ts
+// Minimal usage example
+```
+
+## References
+
+- [Related Guide](../guides/related.md)

package/templates/runbook.liquid

@@ -0,0 +1,65 @@
+# {{title}}
+
+<!-- One sentence: what this procedure accomplishes. -->
+
+## When to Use
+
+- Condition A occurs
+- Condition B is met
+
+## Prerequisites
+
+- Required access
+- Required permissions
+
+## Procedure
+
+### 1. Assess
+
+```bash
+status-command
+```
+
+Expected output:
+
+```
+normal state
+```
+
+### 2. Execute
+
+```bash
+operation-command
+```
+
+**Verify:**
+
+```bash
+verification-command
+```
+
+### 3. Confirm
+
+```bash
+health-check-command
+```
+
+## Rollback
+
+### 1. Revert
+
+```bash
+rollback-command
+```
+
+### 2. Verify
+
+```bash
+verification-command
+```
+
+## Escalation
+
+| Condition       | Contact          | Channel    |
+| --------------- | ---------------- | ---------- |
+| Procedure fails | On-call engineer | #incidents |

package/templates/standard.liquid

@@ -0,0 +1,41 @@
+# {{title}}
+
+<!-- One sentence: what this standard covers. -->
+
+## Overview
+
+Why this standard exists and what it applies to.
+
+## Rules
+
+### Rule Category
+
+| Rule   | Description   | Example       |
+| ------ | ------------- | ------------- |
+| Rule A | What it means | Example usage |
+| Rule B | What it means | Example usage |
+
+## Examples
+
+### Good
+
+```ts
+// Following the standard
+```
+
+### Bad
+
+```ts
+// Violating the standard
+```
+
+## Enforcement
+
+| Rule   | Enforced By   | Severity |
+| ------ | ------------- | -------- |
+| Rule A | Linter / CI   | Error    |
+| Rule B | Code review   | Warning  |
+
+## References
+
+- [Related Standard](./related.md)

package/templates/troubleshooting.liquid

@@ -0,0 +1,34 @@
+# {{title}} Troubleshooting
+
+Common issues and fixes for {{title}}.
+
+## Issue Name
+
+**Symptom:** Brief description (1 line).
+
+**Fix:**
+
+```bash
+solution-command
+```
+
+## Another Issue
+
+**Symptom:** Brief description.
+
+**Cause:** Why this happens.
+
+**Fix:**
+
+1. First step
+2. Second step
+
+## Error: Specific Error Message
+
+**Symptom:** When you see this error:
+
+```
+Error: Something went wrong
+```
+
+**Fix:** Explanation or command.

package/templates/tutorial.liquid

@@ -0,0 +1,58 @@
+# Build Your First {{title}}
+
+<!-- One sentence: what the reader will learn and build. -->
+
+## What You Will Learn
+
+- Learning objective 1
+- Learning objective 2
+- Learning objective 3
+
+## What You Will Build
+
+A working {{title}} that demonstrates concepts A, B, and C.
+
+## Prerequisites
+
+- Prerequisite 1
+- Prerequisite 2
+
+## Steps
+
+### 1. First Step
+
+Brief explanation of what this step does.
+
+```bash
+command here
+```
+
+You should see:
+
+```
+expected output
+```
+
+### 2. Second Step
+
+Brief explanation.
+
+```ts
+// Complete, runnable code
+```
+
+### 3. Third Step
+
+<!-- Continue as needed. Max 7 steps. -->
+
+## Summary
+
+In this tutorial, you learned:
+
+- **Concept A** — what it is and how it works
+- **Concept B** — how to apply it
+
+## Next Steps
+
+- [Guide title](../guides/related.md) — apply what you learned
+- [Concept title](../concepts/related.md) — deeper understanding