@vellum-docs/engine-nunjucks 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { TemplateContext, TemplateEngine } from "@vellum-docs/core";
+
+//#region src/engine.d.ts
+interface NunjucksEngineOptions {
+  /** Extra directories to resolve `{% include %}` / `{% extends %}` from. */
+  searchPaths?: string[];
+  /** Additional Nunjucks globals (merged with built-ins). */
+  globals?: Record<string, unknown>;
+  /** Additional Nunjucks filters (merged with built-ins). */
+  filters?: Record<string, (...args: unknown[]) => unknown>;
+  /** Override the source extension (default `.vel`). */
+  sourceExtension?: string;
+}
+declare class NunjucksEngine implements TemplateEngine {
+  readonly name = "nunjucks";
+  readonly sourceExtension: string;
+  private readonly searchPaths;
+  private readonly extraGlobals;
+  private readonly extraFilters;
+  constructor(opts?: NunjucksEngineOptions);
+  render(source: string, ctx: TemplateContext): Promise<string>;
+}
+//#endregion
+export { NunjucksEngine, type NunjucksEngineOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/engine.ts"],"mappings":";;;UAUiB,qBAAA;;EAEf,WAAA;EAFoC;EAKpC,OAAA,GAAU,MAAA;EAGM;EAAhB,OAAA,GAAU,MAAA,aAAmB,IAAA;EAH7B;EAMA,eAAA;AAAA;AAAA,cAMW,cAAA,YAA0B,cAAA;EAAA,SAC5B,IAAA;EAAA,SACA,eAAA;EAAA,iBAEQ,WAAA;EAAA,iBACA,YAAA;EAAA,iBACA,YAAA;cAEL,IAAA,GAAM,qBAAA;EAOZ,MAAA,CAAO,MAAA,UAAgB,GAAA,EAAK,eAAA,GAAkB,OAAA;AAAA"}

package/dist/index.mjs

@@ -0,0 +1,85 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import nunjucks from "nunjucks";
+//#region src/filters.ts
+function buildFilters(ctx) {
+	const resolve = (id) => ctx.index.symbol(id);
+	const renderCtx = {
+		profile: ctx.profile,
+		resolve
+	};
+	return {
+		mdxLink: (sym) => ctx.profile.link(sym, renderCtx),
+		mdxSignature: (sym) => ctx.profile.signature(sym, renderCtx),
+		typeRef: (sym) => ctx.profile.typeRef(sym, renderCtx),
+		typeCard: (sym) => ctx.profile.typeCard(sym, renderCtx),
+		typeString: (ts) => ctx.profile.typeString(ts, renderCtx),
+		example: (sym, n = 0) => {
+			const ex = sym.doc.examples[n];
+			if (!ex) return "";
+			return ex.code;
+		},
+		summary: (target) => {
+			if (!target) return "";
+			if ("doc" in target) return target.doc.summary;
+			if ("summary" in target) return target.summary;
+			return "";
+		}
+	};
+}
+//#endregion
+//#region src/globals.ts
+function buildGlobals(ctx) {
+	return {
+		symbol: (id) => ctx.index.symbol(id),
+		symbols: (query = {}) => ctx.index.symbols(query),
+		module: (path) => ctx.index.module(path)
+	};
+}
+//#endregion
+//#region src/engine.ts
+const builtinPartialsDir = resolve(dirname(fileURLToPath(import.meta.url)), "./partials");
+var NunjucksEngine = class {
+	name = "nunjucks";
+	sourceExtension;
+	searchPaths;
+	extraGlobals;
+	extraFilters;
+	constructor(opts = {}) {
+		this.sourceExtension = opts.sourceExtension ?? ".vel";
+		this.searchPaths = [builtinPartialsDir, ...opts.searchPaths ?? []];
+		this.extraGlobals = opts.globals ?? {};
+		this.extraFilters = opts.filters ?? {};
+	}
+	async render(source, ctx) {
+		const env = new nunjucks.Environment(new nunjucks.FileSystemLoader(this.searchPaths, {
+			noCache: true,
+			watch: false
+		}), {
+			autoescape: false,
+			throwOnUndefined: false,
+			trimBlocks: false,
+			lstripBlocks: false
+		});
+		const originalGetTemplate = env.getTemplate.bind(env);
+		env.getTemplate = function(name, ...rest) {
+			return originalGetTemplate(name.startsWith("@vellum-docs/partials/") ? name.slice(22) : name, ...rest);
+		};
+		const globals = buildGlobals(ctx);
+		for (const [k, v] of Object.entries(globals)) env.addGlobal(k, v);
+		for (const [k, v] of Object.entries(this.extraGlobals)) env.addGlobal(k, v);
+		const filters = buildFilters(ctx);
+		for (const [k, v] of Object.entries(filters)) env.addFilter(k, v);
+		for (const [k, v] of Object.entries(this.extraFilters)) env.addFilter(k, v);
+		return new Promise((resolvePromise, reject) => {
+			env.renderString(source, {}, (err, result) => {
+				if (err) reject(err);
+				else resolvePromise(result ?? "");
+			});
+		});
+	}
+};
+//#endregion
+export { NunjucksEngine };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/filters.ts","../src/globals.ts","../src/engine.ts"],"sourcesContent":["import type { Symbol, TemplateContext, TypeString } from '@vellum-docs/core'\n\nexport function buildFilters(ctx: TemplateContext) {\n  const resolve = (id: string) => ctx.index.symbol(id)\n  const renderCtx = { profile: ctx.profile, resolve }\n\n  return {\n    mdxLink: (sym: Symbol) => ctx.profile.link(sym, renderCtx),\n    mdxSignature: (sym: Symbol) => ctx.profile.signature(sym, renderCtx),\n    typeRef: (sym: Symbol) => ctx.profile.typeRef(sym, renderCtx),\n    typeCard: (sym: Symbol) => ctx.profile.typeCard(sym, renderCtx),\n    typeString: (ts: TypeString) => ctx.profile.typeString(ts, renderCtx),\n\n    /** Return the nth @example code block, or empty string. */\n    example: (sym: Symbol, n: number = 0) => {\n      const ex = sym.doc.examples[n]\n      if (!ex)\n        return ''\n      return ex.code\n    },\n\n    /** Just the summary from a DocComment (or a Symbol). */\n    summary: (target: Symbol | { summary: string } | null | undefined) => {\n      if (!target)\n        return ''\n      if ('doc' in target)\n        return target.doc.summary\n      if ('summary' in target)\n        return target.summary\n      return ''\n    },\n  }\n}\n","import type { Module, Symbol, SymbolId, SymbolQuery, TemplateContext } from '@vellum-docs/core'\n\nexport interface GlobalFunctions {\n  symbol: (id: SymbolId) => Symbol | null\n  symbols: (query?: SymbolQuery) => Symbol[]\n  module: (path: string) => Module | null\n}\n\nexport function buildGlobals(ctx: TemplateContext): GlobalFunctions {\n  return {\n    symbol: id => ctx.index.symbol(id),\n    symbols: (query = {}) => ctx.index.symbols(query),\n    module: path => ctx.index.module(path),\n  }\n}\n","import type { TemplateContext, TemplateEngine } from '@vellum-docs/core'\nimport { dirname, resolve } from 'node:path'\n\nimport { fileURLToPath } from 'node:url'\n\nimport nunjucks from 'nunjucks'\n\nimport { buildFilters } from './filters'\nimport { buildGlobals } from './globals'\n\nexport interface NunjucksEngineOptions {\n  /** Extra directories to resolve `{% include %}` / `{% extends %}` from. */\n  searchPaths?: string[]\n\n  /** Additional Nunjucks globals (merged with built-ins). */\n  globals?: Record<string, unknown>\n\n  /** Additional Nunjucks filters (merged with built-ins). */\n  filters?: Record<string, (...args: unknown[]) => unknown>\n\n  /** Override the source extension (default `.vel`). */\n  sourceExtension?: string\n}\n\nconst here = dirname(fileURLToPath(import.meta.url))\nconst builtinPartialsDir = resolve(here, './partials')\n\nexport class NunjucksEngine implements TemplateEngine {\n  readonly name = 'nunjucks'\n  readonly sourceExtension: string\n\n  private readonly searchPaths: string[]\n  private readonly extraGlobals: Record<string, unknown>\n  private readonly extraFilters: Record<string, (...args: unknown[]) => unknown>\n\n  constructor(opts: NunjucksEngineOptions = {}) {\n    this.sourceExtension = opts.sourceExtension ?? '.vel'\n    this.searchPaths = [builtinPartialsDir, ...(opts.searchPaths ?? [])]\n    this.extraGlobals = opts.globals ?? {}\n    this.extraFilters = opts.filters ?? {}\n  }\n\n  async render(source: string, ctx: TemplateContext): Promise<string> {\n    const env = new nunjucks.Environment(\n      new nunjucks.FileSystemLoader(this.searchPaths, {\n        noCache: true,\n        watch: false,\n      }),\n      { autoescape: false, throwOnUndefined: false, trimBlocks: false, lstripBlocks: false },\n    )\n\n    // Path alias: `{% include \"@vellum-docs/partials/...\" %}` → built-in partials dir.\n    type GetTemplateFn = (name: string, ...rest: unknown[]) => unknown\n    const originalGetTemplate = (env as unknown as { getTemplate: GetTemplateFn }).getTemplate.bind(env);\n    (env as unknown as { getTemplate: GetTemplateFn }).getTemplate = function (\n      name: string,\n      ...rest: unknown[]\n    ) {\n      const resolved = name.startsWith('@vellum-docs/partials/')\n        ? name.slice('@vellum-docs/partials/'.length)\n        : name\n      return originalGetTemplate(resolved, ...rest)\n    }\n\n    const globals = buildGlobals(ctx)\n    for (const [k, v] of Object.entries(globals)) env.addGlobal(k, v as never)\n    for (const [k, v] of Object.entries(this.extraGlobals)) env.addGlobal(k, v as never)\n\n    const filters = buildFilters(ctx)\n    for (const [k, v] of Object.entries(filters)) env.addFilter(k, v)\n    for (const [k, v] of Object.entries(this.extraFilters)) env.addFilter(k, v)\n\n    return new Promise<string>((resolvePromise, reject) => {\n      env.renderString(source, {}, (err, result) => {\n        if (err)\n          reject(err)\n        else resolvePromise(result ?? '')\n      })\n    })\n  }\n}\n"],"mappings":";;;;AAEA,SAAgB,aAAa,KAAsB;CACjD,MAAM,WAAW,OAAe,IAAI,MAAM,OAAO,GAAG;CACpD,MAAM,YAAY;EAAE,SAAS,IAAI;EAAS;EAAS;AAEnD,QAAO;EACL,UAAU,QAAgB,IAAI,QAAQ,KAAK,KAAK,UAAU;EAC1D,eAAe,QAAgB,IAAI,QAAQ,UAAU,KAAK,UAAU;EACpE,UAAU,QAAgB,IAAI,QAAQ,QAAQ,KAAK,UAAU;EAC7D,WAAW,QAAgB,IAAI,QAAQ,SAAS,KAAK,UAAU;EAC/D,aAAa,OAAmB,IAAI,QAAQ,WAAW,IAAI,UAAU;EAGrE,UAAU,KAAa,IAAY,MAAM;GACvC,MAAM,KAAK,IAAI,IAAI,SAAS;AAC5B,OAAI,CAAC,GACH,QAAO;AACT,UAAO,GAAG;;EAIZ,UAAU,WAA4D;AACpE,OAAI,CAAC,OACH,QAAO;AACT,OAAI,SAAS,OACX,QAAO,OAAO,IAAI;AACpB,OAAI,aAAa,OACf,QAAO,OAAO;AAChB,UAAO;;EAEV;;;;ACvBH,SAAgB,aAAa,KAAuC;AAClE,QAAO;EACL,SAAQ,OAAM,IAAI,MAAM,OAAO,GAAG;EAClC,UAAU,QAAQ,EAAE,KAAK,IAAI,MAAM,QAAQ,MAAM;EACjD,SAAQ,SAAQ,IAAI,MAAM,OAAO,KAAK;EACvC;;;;ACYH,MAAM,qBAAqB,QADd,QAAQ,cAAc,OAAO,KAAK,IAAI,CAAC,EACX,aAAa;AAEtD,IAAa,iBAAb,MAAsD;CACpD,OAAgB;CAChB;CAEA;CACA;CACA;CAEA,YAAY,OAA8B,EAAE,EAAE;AAC5C,OAAK,kBAAkB,KAAK,mBAAmB;AAC/C,OAAK,cAAc,CAAC,oBAAoB,GAAI,KAAK,eAAe,EAAE,CAAE;AACpE,OAAK,eAAe,KAAK,WAAW,EAAE;AACtC,OAAK,eAAe,KAAK,WAAW,EAAE;;CAGxC,MAAM,OAAO,QAAgB,KAAuC;EAClE,MAAM,MAAM,IAAI,SAAS,YACvB,IAAI,SAAS,iBAAiB,KAAK,aAAa;GAC9C,SAAS;GACT,OAAO;GACR,CAAC,EACF;GAAE,YAAY;GAAO,kBAAkB;GAAO,YAAY;GAAO,cAAc;GAAO,CACvF;EAID,MAAM,sBAAuB,IAAkD,YAAY,KAAK,IAAI;AACnG,MAAkD,cAAc,SAC/D,MACA,GAAG,MACH;AAIA,UAAO,oBAHU,KAAK,WAAW,yBAAyB,GACtD,KAAK,MAAM,GAAgC,GAC3C,MACiC,GAAG,KAAK;;EAG/C,MAAM,UAAU,aAAa,IAAI;AACjC,OAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,QAAQ,CAAE,KAAI,UAAU,GAAG,EAAW;AAC1E,OAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,aAAa,CAAE,KAAI,UAAU,GAAG,EAAW;EAEpF,MAAM,UAAU,aAAa,IAAI;AACjC,OAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,QAAQ,CAAE,KAAI,UAAU,GAAG,EAAE;AACjE,OAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,aAAa,CAAE,KAAI,UAAU,GAAG,EAAE;AAE3E,SAAO,IAAI,SAAiB,gBAAgB,WAAW;AACrD,OAAI,aAAa,QAAQ,EAAE,GAAG,KAAK,WAAW;AAC5C,QAAI,IACF,QAAO,IAAI;QACR,gBAAe,UAAU,GAAG;KACjC;IACF"}

package/dist/partials/constant-table.njk

@@ -0,0 +1,6 @@
+{%- set consts = symbols({ module: module, kind: "const" }) -%}
+| Name | Value | Description |
+| ---- | ----- | ----------- |
+{%- for c in consts %}
+| `{{ c.name }}` | `{{ c.value.text if c.value else "" }}` | {{ c.doc.summary }} |
+{%- endfor %}

package/dist/partials/function-signature.njk

@@ -0,0 +1,17 @@
+{%- if sym -%}
+{{ sym | mdxSignature | safe }}
+
+{%- if sym.parameters and sym.parameters.length > 0 %}
+
+**Parameters**
+
+{%- for p in sym.parameters %}
+- **`{{ p.name }}`**{% if p.optional %} _(optional)_{% endif %} — `{{ p.type.text }}`{% if p.doc %} — {{ p.doc }}{% endif %}
+{%- endfor %}
+{%- endif %}
+
+{%- if sym.returnType and sym.returnType.text %}
+
+**Returns** — `{{ sym.returnType.text }}`{% if sym.doc.returns %} — {{ sym.doc.returns }}{% endif %}
+{%- endif %}
+{%- endif %}

package/dist/partials/type-card.njk

@@ -0,0 +1,23 @@
+{%- if sym -%}
+### {{ sym.name }}
+
+{{ sym.doc.summary }}
+
+{{ sym | mdxSignature | safe }}
+
+{%- if sym.doc.description %}
+
+{{ sym.doc.description }}
+{%- endif %}
+
+{%- if sym.doc.examples.length > 0 %}
+
+**Examples**
+
+{%- for ex in sym.doc.examples %}
+```{{ ex.lang }}
+{{ ex.code }}
+```
+{%- endfor %}
+{%- endif %}
+{%- endif %}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@vellum-docs/engine-nunjucks",
+  "type": "module",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/photon-hq/vellum.git",
+    "directory": "packages/engine-nunjucks"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "partials"
+  ],
+  "dependencies": {
+    "nunjucks": "^3.2.4",
+    "@vellum-docs/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/nunjucks": "^3.2.6",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --out-dir dist --dts && cp -r src/partials dist/partials",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}