Deelan

Data Engineering Electronic LAboratory Notebook.
Elevate your note-keeping experience.

Deelan is designed for people who want a durable, searchable, versioned knowledge base that stays close to plain text authoring and yet provides a useful, scaleable, and beautiful web-based view to navigate contents.

You keep Markdown-formatted notes with rich authoring features in a simple git repo.
Deelan creates a beautiful, scalable, private, and feature-rich navigation experience with just a handful of configuration files and CLI commands.

What Deelan Gives You

• Post + snippet content model with frontmatter validation. Templates provided for VSCode and Obsidian.
• Quickly find contents with an advanced search grammar, hierarchical tags, date ranges, and more.
• Rich rendered views out-of-the-box with code highlighting, Mathjax, git timelines, internal links, and more.
• Static, local-first workflow (offline-friendly), with guidance and templates for secure private deployment.
• Export to self-contained HTML and PDF, share permalinks, explore and extend analytics.

[!NOTE] Deelan is currently published as an early 0.x experimental workflow. Expect iterative changes to CLI surface, generated outputs, and docs while the release hardening pass continues.

Install

From npm (once published):

npm install -g @jhadida/deelan
deelan --help

Without global install:

npx @jhadida/deelan --help

Repository-local usage for contributors:

node ./bin/deelan.mjs --help

Quickstart

deelan init my-notebook
cd my-notebook
deelan validate
deelan build
deelan serve

Open http://localhost:4321.

Core Commands

deelan --help
deelan init --help
deelan validate --help
deelan build --help
deelan serve --help
deelan tags --help
deelan export --help

Optional PDF export dependencies:

npm install playwright
npx playwright install chromium

High Level Guidance

Markdown files are stored in a content/ folder for both posts and snippets. Content IDs are filename-derived and type-prefixed:

• content/posts/partitioning-primer.md -> post--partitioning-primer
• content/snippets/pandas-groupby.md -> snippet--pandas-groupby

These IDs are used by search, related links, routes, and export commands. Tags can be assigned to posts and snippets alike, and are hierarchical in nature with dot-separators e.g. python.pandas.groupby. Content assets (like figures) are typically stored under an asset folder content/<type>/assets/. We strongly recommend versioning text contents with Git and non-text assets with LFS.

Project settings live in deelan.config.yml. Common options include default theme, timezone for rendered timestamps, and code highlighting themes. Learn more about typical workflows, and many more topics, in the documentation.

About this app

Created by Jonathan Hadida proudly with the help of GPT-5.3-Codex and minimal permissive dependencies (MIT/Apache-2.0 only for top-level dependencies).