Obsidian: Automatic Index/JDex Generation (Area/Category Modes)

J.D Concepts 31 Apps and utilities
1

Hello fellow JohnnyDecimal & Obsidian users!

I wanted to share a Templater user script I’ve made to help automate the process of generating JDex for new notes. If you use the JohnnyDecimal system to organize your vault, you know that finding the next sequential ID in a category can be a manual step. This script aims to solve that!

What it Does
This script, named JDFormatter, provides a function you can call from your Obsidian templates to automatically:

  1. Find the Next ID: Scans a specified JohnnyDecimal category folder for existing files named like XX.YY ... (e.g., 12.05 Meeting Notes.md).
  2. Calculate Increment: Determines the highest existing YY number for that category (XX).
  3. Generate New ID: Calculates the next sequential ID (maxId + 1), ensuring it starts from a minimum value (default is 11).
  4. Two Operating Modes:
    • area mode (default): You provide the path to an “Area” folder (e.g., "10 - 19 Finance"). The script will then prompt you using Templater’s suggester to choose a specific “Category” folder within that area (e.g., "11 Banking", "12 Bills").
    • category mode: You provide the direct path to a specific “Category” folder (e.g., "10 - 19 Finance/12 Bills"). The script will process this folder directly without prompting.
  5. Return Useful Data: Returns a JavaScript object containing information about the selected category (ID number XX, path, name, tag-friendly formatted name) and the newly generated full JDex string (XX.YY).

Requirements

  • Templater Plugin: Installed and enabled.
  • User Scripts Enabled: You need to enable the “User Scripts Functions” option within the Templater plugin settings and specify a folder where your scripts reside.
  • Folder/File Structure: Your vault needs to follow the expected JohnnyDecimal structure for this script to work correctly:
    • Category Folders: Named like XX Name (e.g., 01 Quick Note, 21 Active Projects). The script uses a regular expression (/^(\d{2})\s(.+)/) to find these.
    • Files within Categories: Named like XX.YY Title.md (e.g., 01.11 Daily Log, 21.15 Project Alpha Kickoff.md). The script uses a regular expression (/^(\d{2})\.(\d{2,})\s.+/) to find the ID (YY) part.

Installation

  1. Create Script File: Copy the code provided below and save it as a .js file (e.g., JDFormatter.js).
  2. Place in Script Folder: Move this .js file into the folder you’ve designated for Templater User Scripts in the Templater settings.
  3. Enable Scripts: Double-check that “User Script Functions” is toggled ON in Templater settings and the folder path is correct.

How to Use
You call this function from within a Templater template (<%* ... %> block).

Syntax:

const jdInfo = await tp.user.JDFormatter(tp, BASE_DIR, MODE);
  • tp: The Templater object (always pass this).
  • BASE_DIR: String containing the path to the Area folder (for area mode) or the Category folder (for category mode).
  • MODE: Optional string, either "area" (default) or "category". Case-insensitive.

Example 1: Area Mode (Default - Prompts for Category)
Let’s say you have a template to create a new bill record.

<%*
// Define the Area folder for finance
const AREA_FOLDER = "10 - 19 Finance";

// Call the script (mode defaults to "area")
// It will prompt you to select a category like "11 Banking", "12 Bills", etc.
const jdInfo = await tp.user.JDFormatter(tp, AREA_FOLDER);

// If user cancelled the category prompt or an error occurred
if (!jdInfo) {
    new Notice("JD ID generation cancelled or failed.", 3000);
    return ""; // Stop template execution
}

// jdInfo now contains:
// jdInfo.category.id          -> e.g., "12" (if you selected "12 Bills")
// jdInfo.category.path        -> e.g., "10 - 19 Finance/12 Bills"
// jdInfo.category.name        -> e.g., "Bills"
// jdInfo.category.formattedName -> e.g., "bills"
// jdInfo.generatedId        -> e.g., "12.14" (the next calculated ID)

// Suggest a filename
const suggestedFilename = `${jdInfo.generatedId} New Bill Title`;
const finalFilename = await tp.system.prompt("Enter filename:", suggestedFilename);

if (!finalFilename || !finalFilename.startsWith(jdInfo.generatedId)) {
    new Notice("Filename invalid or cancelled.", 3000);
    return "";
}

// Move the new note (created by Templater) to the correct category and rename it
await tp.file.move(`${jdInfo.category.path}/${finalFilename}`);

// Optional: Display a confirmation
new Notice(`Note created in ${jdInfo.category.name}: ${finalFilename}`, 3000);
%>---
tags: <% jdInfo.category.formattedName %> #finance #<% jdInfo.category.id %>
jd_id: <% jdInfo.generatedId %>
category: <% `${jdInfo.category.id} ${jdInfo.category.name}` %>
status: unprocessed
---

# <% finalFilename.replace(/.md$/,'') %>

- Amount:
- Due Date:
- Paid Date:

Example 2: Category Mode (Direct - No Prompt)
If your template always creates notes in one specific category.

<%*
// Define the *specific* Category folder
const CATEGORY_FOLDER = "00 - 09 System/01 Quick Note";

// Call the script explicitly in "category" mode
const jdInfo = await tp.user.JDFormatter(tp, CATEGORY_FOLDER, "category");

// Error check (e.g., if folder doesn't exist or has wrong name format)
if (!jdInfo) {
    new Notice("JD ID generation failed. Check category path/name.", 3000);
    return "";
}

// Suggest filename directly
const suggestedFilename = `${jdInfo.generatedId} Quick Note Title`;
const finalFilename = await tp.system.prompt("Enter filename:", suggestedFilename);

if (!finalFilename || !finalFilename.startsWith(jdInfo.generatedId)) {
    new Notice("Filename invalid or cancelled.", 3000);
    return "";
}

// Move and rename
await tp.file.move(`${jdInfo.category.path}/${finalFilename}`);
%>---
tags: <% jdInfo.category.formattedName %> #quicknote
jd_id: <% jdInfo.generatedId %>
---

# <% finalFilename.replace(/.md$/,'') %>

<% tp.date.now("YYYY-MM-DD HH:mm") %>

The Script Code

/**
 * Generates the next sequential JohnnyDecimal ID. Operates in two modes:
 * - "area": Prompts user to select a category within the BASE_DIR (Area folder).
 * - "category": Assumes BASE_DIR is the specific category folder to generate an ID for.
 *
 * @param {object} tp - The Templater instance provided by Templater.
 * @param {string} BASE_DIR - The path to the "Area" directory (mode="area") or "Category" directory (mode="category").
 * @param {string} [MODE="area"] - The operating mode: "area" or "category". Case-insensitive.
 * @returns {Promise<object|null>} A promise that resolves to an object containing category info and the next ID,
 *                                 or null if the process is cancelled or fails.
 *                                 Object structure:
 *                                 {
 *                                   category: {
 *                                     id: string, // e.g., "01"
 *                                     path: string,
 *                                     name: string, // e.g., "Quick Note"
 *                                     formattedName: string // e.g., "quick-note"
 *                                   },
 *                                   generatedId: string // e.g., "01.13"
 *                                 }
 */
async function JDFormatter(tp, BASE_DIR, MODE = "area") {
	// --- Configuration ---
	const STARTING_ID = 11;
	const CATEGORY_REGEX = /^(\d{2})\s(.+)/;
	const FILE_ID_REGEX = /^(\d{2})\.(\d{2,})\s.+/;

	// --- Helper for Name Formatting ---
	function formatCategoryName(name) {
		if (!name) return "";
		return name
			.toLowerCase()
			.replace(/\s+/g, "-")
			.replace(/[^\w-]+/g, "")
			.replace(/^-+|-+$/g, "");
	}

	// --- Input Validation ---
	if (!BASE_DIR) {
		const msg = "JDFormatter: BASE_DIR parameter is required.";
		console.error(msg);
		await new Notice(msg);
		return null;
	}

	const baseAbstractFile = tp.app.vault.getAbstractFileByPath(BASE_DIR);
	if (!baseAbstractFile) {
		const msg = `JDFormatter: BASE_DIR "${BASE_DIR}" not found.`;
		console.error(msg);
		await new Notice(msg);
		return null;
	}

	// --- Mode Handling Variables ---
	let categoryFolder; // The TFolder object for the target category
	let categoryNumber; // The "XX" part
	let categoryName; // The "Name" part
	let categoryPath; // Full path to the category folder

	const effectiveMode = MODE.toLowerCase();

	// --- Determine Category Details Based on Mode ---
	if (effectiveMode === "category") {
		// Mode: BASE_DIR *is* the category folder
		if (baseAbstractFile.children === undefined) {
			const msg = `JDFormatter (Category Mode): BASE_DIR "${BASE_DIR}" is not a valid folder.`;
			console.error(msg);
			await new Notice(msg);
			return null;
		}
		categoryFolder = baseAbstractFile;

		const match = categoryFolder.name.match(CATEGORY_REGEX);
		if (!match) {
			const msg = `JDFormatter (Category Mode): Folder name "${categoryFolder.name}" does not match expected 'XX Name' format.`;
			console.error(msg);
			await new Notice(msg);
			return null;
		}
		categoryNumber = match[1];
		categoryName = match[2];
		categoryPath = categoryFolder.path;
		console.log(`JDFormatter: Running in Category mode for "${categoryPath}"`);
	} else if (effectiveMode === "area") {
		// Mode: BASE_DIR is the area folder, prompt for category
		if (baseAbstractFile.children === undefined) {
			const msg = `JDFormatter (Area Mode): BASE_DIR "${BASE_DIR}" is not a valid folder.`;
			console.error(msg);
			await new Notice(msg);
			return null;
		}
		const areaFolder = baseAbstractFile;

		const categoryFolders = areaFolder.children
			.filter(
				(item) => item.children !== undefined && CATEGORY_REGEX.test(item.name),
			)
			.map((folder) => ({
				name: folder.name,
				path: folder.path,
				display: folder.name,
			}))
			.sort((a, b) => a.name.localeCompare(b.name));

		if (categoryFolders.length === 0) {
			const msg = `JDFormatter (Area Mode): No valid category folders (like "XX Name") found in "${BASE_DIR}".`;
			console.error(msg);
			await tp.templater.warning(msg);
			return null;
		}

		console.log(`JDFormatter: Running in Area mode for "${BASE_DIR}", prompting for category...`);
		const selectedCategory = await tp.system.suggester(
			categoryFolders.map((f) => f.display),
			categoryFolders,
		);

		if (!selectedCategory) {
			console.log("JDFormatter (Area Mode): User cancelled category selection.");
			return null;
		}

		const selectedFolderObject = tp.app.vault.getAbstractFileByPath(selectedCategory.path);
		categoryFolder = selectedFolderObject;

		// Extract details from selected category
		const categoryMatch = selectedCategory.name.match(CATEGORY_REGEX);
		categoryNumber = categoryMatch[1];
		categoryName = categoryMatch[2];
		categoryPath = selectedCategory.path;
		console.log(`JDFormatter: User selected category "${categoryPath}"`);
	} else {
		// Invalid Mode Handling
		const msg = `JDFormatter: Invalid MODE "${MODE}". Use "area" or "category".`;
		console.error(msg);
		await new Notice(msg);
		return null;
	}

	// --- Scan the Determined Category Folder for Existing IDs ---
	if (!categoryFolder || !categoryNumber || !categoryName || !categoryPath) {
		const msg = "JDFormatter: Internal Error - category details were not determined correctly.";
		console.error(msg);
		await new Notice(msg);
		return null;
	}

	let maxId = STARTING_ID - 1; // Initialize below the minimum starting ID

	try {
		const files = categoryFolder.children;
		for (const file of files) {
			// Check if it's a file (doesn't have .children)
			if (file.children === undefined) {
				const match = file.name.match(FILE_ID_REGEX);
				// Check if file belongs to the *correct* category (XX matches) and has an ID
				if (match && match[1] === categoryNumber) {
					const currentId = Number.parseInt(match[2], 10);
					if (!Number.isNaN(currentId)) {
						maxId = Math.max(maxId, currentId);
					}
				}
			}
		}
	} catch (error) {
		console.error(`JDFormatter: Error scanning files in category "${categoryPath}":`, error);
		await new Notice(`Error scanning category folder "${categoryPath}". Check console.`);
		return null;
	}

	// --- Calculate Next ID ---
	const nextId = Math.max(STARTING_ID, maxId + 1);

	return {
		category: {
			id: categoryNumber,
			path: categoryPath,
			name: categoryName,
			formattedName: formatCategoryName(categoryName),
		},
		generatedId: `${categoryNumber}.${nextId.toString().padStart(2, "0")}`,
	};
}

module.exports = JDFormatter;

Configuration / Customization
You can tweak the script slightly by editing these constants near the top:

  • STARTING_ID: Change 11 if you want your IDs to start from a different number (e.g., 1 for XX.01).
  • CATEGORY_REGEX: Modify this regular expression if your category folders have a different naming pattern than XX Name.
  • FILE_ID_REGEX: Modify this regular expression if your files have a different naming pattern for extracting the XX.YY ID.
    Warning: Modifying regex requires understanding regular expressions.

Important Notes

  • Naming Convention is Crucial: This script heavily relies on your folders being named XX Name and files XX.YY .... If your convention differs, you must update the CATEGORY_REGEX and FILE_ID_REGEX constants accordingly.
  • Error Handling: Errors (e.g., folder not found, invalid name format) will usually display an Obsidian Notice message and log details to the Developer Console (press Ctrl+Shift+I or Cmd+Opt+I to open it).
  • Performance: The script reads the list of files in the target category. In extremely large categories (thousands of files), there might be a slight delay, but it should be negligible for most use cases.

Hope this is helpful for other JohnnyDecimal users in Obsidian! Let me know if you found any bugs or have any questions and suggestions. :grin:

1 Like