KnForge

KnForge creates consistent, self-contained Markdown packages in Obsidian. Choose a template, enter a name, and KnForge creates a package folder, an optional subfolder structure, and a Markdown file that is opened immediately.

KnForge is designed for repeatable note structures such as research topics, projects, meetings, customers, technical records, and knowledge objects. It works entirely inside your Vault and keeps the generated content as portable Markdown with optional YAML frontmatter.

Features

• Select templates from a configurable Vault folder.
• Discover Markdown templates recursively in nested template folders.
• Create a predictable <name>/<name>.md package layout.
• Create any number of configured subfolders with each package.
• Place packages in the Vault root, beside the active note, or in a configured Vault folder.
• Substitute date, title, and unique-ID variables in templates and folder paths.
• Optionally generate and merge YAML frontmatter.
• Choose whether template YAML or KnForge YAML wins when a key exists in both.
• Validate names, paths, templates, and YAML before writing package content.
• Open the generated Markdown file automatically.
• Create a package directly inside a folder from the file explorer context menu.
• Localize supported images, linked videos, and PDFs pasted from rendered Markdown previews, web pages, and other applications into an assets folder.
• Use configurable short attachment names and size limits while retaining portable Markdown links and preventing file overwrites.
• Display menus, dialogs, settings, notices, and validation errors in English or Simplified Chinese according to Obsidian's interface language.
• Run on desktop and mobile without external services.

Requirements

• Obsidian 1.13.0 or later
• Community plugins enabled

Language support

KnForge follows Obsidian's interface language automatically. English and Simplified Chinese are included. Other Obsidian languages currently fall back to English, and additional translations can be added without changing package creation behavior.

Installation

From the Obsidian community plugin directory

After KnForge has been accepted into the community directory:

1. Open Settings → Community plugins.
2. Select Browse.
3. Search for KnForge.
4. Select Install, then Enable.

Manual installation

1. Download and extract the latest KnForge release package.
2. Create <your-vault>/.obsidian/plugins/knforge/ if it does not exist.
3. Copy main.js, manifest.json, and versions.json into that folder.
4. Reload Obsidian.
5. Open Settings → Community plugins and enable KnForge.

README.md is included in release packages for reference but is not required by Obsidian at runtime.

Quick start

1. Open Settings → KnForge.
2. Select the Vault folder containing your Markdown templates.
3. Configure the subfolders that should be created in every package.
4. Choose the default package location.
5. Optionally enable and configure KnForge YAML frontmatter.
6. Click the KnForge ribbon icon, run KnForge: New package from the command palette, or right-click a folder and choose Create Package with KnForge.
7. Select a template, enter a package name, and select Create.

KnForge creates the package and opens its Markdown file.

Pasted attachment localization

When rich content copied from a web page or a rendered Markdown preview is pasted into an active note, KnForge saves supported images, linked videos, and PDFs in an assets folder beside that note and rewrites their links. It supports clipboard files, data: images, HTTP/HTTPS links, and local file:// links in the Obsidian desktop app. Images use standard Markdown image links; other attachments use standard Markdown links.

Copied attachments receive short names such as asset-001.png, preserving their type without carrying long or URL-encoded source names into the vault. Settings can switch to type prefixes (img, gif, video, pdf) and add a Moment date/time format such as YYYYMMDDHHmmss before the sequence. The sequence increases within each assets folder and starts at 001 in a new folder. Existing files are never overwritten. The per-attachment and per-paste limits default to 20 MiB and 200 MiB; each can be changed independently or set to 0 for no limit. Unlimited downloads can use substantial memory. If an attachment cannot be copied, its original link is retained and KnForge reports a partial result. Pure Markdown text containing only relative attachment paths does not include the source file location; KnForge leaves it unchanged and shows a notice.

How package creation works

With a creation location of Projects, a package name of Windchill, and this folder structure:

assets
references
exports

KnForge creates:

Projects/
└── Windchill/
    ├── Windchill.md
    ├── assets/
    ├── references/
    └── exports/

The contents of Windchill.md come from the template selected in the creation dialog.

Settings reference

Template folder

Start typing any part of a Vault folder path. KnForge displays matching folders using Obsidian's suggestion interface. Select a suggestion to use that folder.

KnForge recursively discovers every .md file in the selected folder and its subfolders. Templates are displayed relative to the template folder, so a file at Templates/Projects/Meeting.md appears as Projects/Meeting.md.

Selecting the Vault root makes every Markdown file in the Vault available as a template. For most Vaults, a dedicated template folder is recommended.

Folder structure

Enter one package subfolder per line:

assets
references
exports

Nested paths are supported:

assets/images
assets/documents
references

Folder entries can use the same variables as templates. Every resulting path is validated before KnForge writes the package.

Default creation location

KnForge follows the location choices used by Obsidian's Files and links settings:

• Vault folder creates package folders in the Vault root.
• Same folder as current file creates the package inside the folder containing the active note. With A/A.md active, creating B produces A/B/B.md.
• Parent of current file's folder creates the package one level above the folder containing the active note. With A/A.md active, creating B produces B/B.md beside A. When the active note is in the Vault root, the Vault root is retained.
• In the folder specified below reveals another folder-path field. Start typing part of a path and select a matching Vault folder.

The additional folder setting is hidden unless the custom-folder option is selected.

Folder suggestions

The template and custom-location fields are editable path inputs rather than fixed dropdowns. Matching is case-insensitive and can match any part of a folder path. An empty query also offers the Vault root.

Generate YAML frontmatter

This option is disabled by default. When disabled, KnForge does not generate or modify YAML; the selected template is used as-is after variable substitution.

When enabled, two additional settings appear:

• KnForge YAML contains the YAML mapping to generate.
• YAML conflict priority decides which source wins when the template and KnForge define the same top-level key.

Example KnForge YAML:

title: "{{title}}"
type: project
status: draft
created: "{{date}}"

Conflict priority

Given template frontmatter:

type: meeting
owner: Hubert

and KnForge YAML:

type: project
status: draft

• Template wins produces type: meeting.
• KnForge wins produces type: project.
• owner and status are retained in both modes because they do not conflict.

Merging is performed on top-level YAML keys. When YAML generation is enabled, frontmatter is parsed and serialized again; comments, quoting choices, and manual formatting inside the original YAML may be normalized.

Template variables

Variables can be used in template content, KnForge YAML, and configured package subfolder paths. KnForge renders these variables itself because Obsidian does not expose the core Templates renderer as a public plugin API.

Obsidian Templates-compatible variables

KnForge follows the core Obsidian Templates syntax for title, date, and time:

Examples include {{date:YYYY/MM/DD}}, {{date:dddd, MMMM Do YYYY}}, and {{time:HH:mm:ss}}.

KnForge extensions

Unknown variables stop creation and display an error instead of silently producing an unexpected path or document. Formatting suffixes are supported only on date and time.

Templater compatibility

KnForge does not interpret Templater expressions. To use complete <% tp... %> expressions, install and enable Templater, then enable Templater's Trigger Templater on new file creation setting. Set Template matching mode to None. No folder-template rule is needed because KnForge has already written the selected template into the new Markdown file.

KnForge first renders its {{...}} variables and, when enabled, merges shared KnForge YAML with the template's existing frontmatter. It then creates the file with Templater expressions intact. Templater processes those expressions in response to the new-file event. Template properties and shared KnForge properties can therefore be used together; YAML conflict priority decides which value wins for duplicate top-level keys. KnForge shared properties always appear first in the generated frontmatter, in the same order as the KnForge YAML setting. Template-only properties follow in their original order.

Recommended Templater settings:

Trigger Templater on new file creation: On
Template matching mode: None

Avoid Folder templates for this integration. Folder and regex template modes are designed to populate empty new files, while KnForge creates a complete file from its selected template. Templater processes that file asynchronously after creation, so expressions may remain visible briefly before their values appear.

Templater integration check

For a manual integration check, configure shared KnForge YAML such as:

id: "{{id}}"
status: draft
created_by: human

and select a template containing:

---
title: <% tp.file.title %>
created: <% tp.date.now("YYYY-MM-DD") %>
type: resource
---

After KnForge creates the package and Templater finishes processing the new file, verify that the package folders and Markdown file exist, id, status, and created_by contain KnForge values, and title and created contain values generated by Templater.

Markdown and YAML portability

KnForge does not require proprietary syntax in generated files:

• Markdown content is ordinary text supplied by the selected template.
• Optional frontmatter is emitted as a YAML mapping between --- delimiters.
• KnForge does not automatically generate Obsidian wiki links, embeds, callouts, Dataview expressions, or other Obsidian-specific Markdown extensions.

YAML frontmatter is a widely supported Markdown ecosystem convention, but it is not part of the CommonMark specification itself. Disable KnForge YAML if you need the generated file to contain only the selected Markdown template.

KnForge does not remove Obsidian-specific syntax already present in a template. Template authors control the portability of template content.

Validation and safety

KnForge validates the complete creation plan before writing package content:

• Package names cannot be empty.
• Characters that are unsafe in filenames are replaced.
• Absolute paths and parent-directory traversal are rejected.
• Template paths must resolve to Markdown files inside the Vault.
• KnForge YAML must be a valid YAML object.
• Existing package paths are not overwritten.
• Files that block a required folder cause creation to stop with an error.

KnForge only reads and writes files inside the current Vault. It does not make network requests, collect telemetry, display advertising, or require an online account.

Troubleshooting

No templates are shown

• Confirm that Template folder points to an existing Vault folder.
• Confirm that the folder or one of its subfolders contains .md files.
• If the configured folder was renamed or deleted, select it again from the folder suggestions.

A package is created in the Vault root

If a current-file-relative location is selected but no note is active, the Vault root is used. Open the desired note before invoking KnForge, or select a fixed folder in settings.

YAML creation fails

KnForge YAML must contain a mapping of keys to values. A list or scalar at the document root is not accepted. For example, use:

tags:
  - research
  - active

instead of a root-level list.

A package already exists

KnForge intentionally refuses to overwrite an existing package folder. Choose a different package name or move the existing package first.

Privacy and permissions

KnForge operates locally inside the active Vault. It has no network integration, telemetry, analytics, advertisements, payment features, or external account requirements. Like all Obsidian community plugins, it runs with Obsidian's file access permissions.

Development

pnpm install
pnpm lint
pnpm test
pnpm build

The production build writes main.js in the repository root. The lint command uses Obsidian's community-plugin ESLint rules. Automated tests cover path safety, template discovery, location handling, declarative settings, variable rendering, localization, and YAML conflict behavior.

Release changes are documented in CHANGELOG.md.

Feedback and support

Use the GitHub repository's issue tracker to report bugs or request features. When reporting a problem, include your Obsidian version, KnForge version, platform, relevant settings, and steps to reproduce the issue. Do not include private Vault content or credentials.