isHistory CMS

Your Astro website's control panel — inside Obsidian.

Write your blog posts and research notes in Obsidian. This plugin checks they're perfect, then helps you publish them to your Astro website.

---

What Does This Plugin Do?

Think of it like a spell-checker for your blog posts, but instead of checking spelling, it checks that every post has all the information your Astro website needs to display it properly.

Here's what you get:

Feature	What It Means
Dashboard	See all your blog posts in one place, like a spreadsheet
Validation	The plugin tells you if a post is missing something (like a title or date)
Pre-flight	Marks a draft as ready for deployment (frontmatter only; deploy via Git sync)
Quick validate sidebar	See errors on the post you're currently editing
Bulk pre-flight	Mark many draft posts as ready for deployment at once
Track system	Organize posts by type — articles, profiles, or events
Status bar	See your content health at a glance in Obsidian's status bar
Sort & filter	Find posts fast with sort options, search, and filters
Context menus	Right-click files for quick validate and pre-flight actions
Safe upgrades	Settings automatically merge when you update — nothing is lost
Mobile support	Responsive dashboard that works on Obsidian Mobile
Accessibility	ARIA labels, keyboard navigation, and screen reader support
Differential rendering	Only changed cards update — fast even with hundreds of posts

---

Installation

Option 1: Community Plugin Store (Recommended)

1. Open Obsidian
2. Go to Settings (the gear icon in the bottom left)
3. Click Community plugins
4. Click Browse
5. Search for "isHistory CMS"
6. Click Install, then click Enable

Option 2: Manual Install

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create a folder at .obsidian/plugins/ishistory-cms/ in your vault
3. Place the three files inside that folder
4. Open Settings → Community plugins and enable "isHistory CMS"

Option 3: BRAT (For Beta Testers)

1. Install the BRAT plugin
2. Go to BRAT settings → Add Beta plugin
3. Paste: https://github.com/dr-ishaan/astro-cms-obsidian-plugin
4. Click Add Plugin
5. Enable "isHistory CMS" in Community plugins

After Installation

1. Look at the left sidebar in Obsidian — you'll see a new dashboard icon (you can hide it in Settings → Appearance)
2. Click it to open your Astro CMS dashboard
3. Or press Ctrl+P (or Cmd+P on Mac) and search for "Open isHistory dashboard"

---

How to Set Up Your Vault

Your Obsidian vault needs to look like your Astro project's content folder for the plugin to find your posts.

The plugin looks for content inside src/content by default. Your vault should have this structure:

your-vault/
  src/
    content/
      blog/           ← Your blog posts (archive collection)
        A1-the-ancient-dream-of-artificial-life.md
        P1-ada-lovelace.md
        E1-the-dartmouth-conference-1956.md
        ...
      vault/          ← Your research notes (vault collection)
        vision-and-architecture.md
        content-schema.md
        ...

The easiest way: Open your entire Astro project folder as your Obsidian vault. That way, the src/content path matches automatically.

If Your Content Is Somewhere Else

1. Go to Settings → isHistory CMS
2. Change the Archive path or Vault path to wherever your content lives
3. For example, if you just have blog posts in a posts/ folder, type posts

---

How to Write a Blog Post

Every blog post needs a special block at the very top called frontmatter. It tells your Astro website everything it needs to know about the post.

Blog Post Template (Archive Collection)

Copy this template and fill in your own information:

---
title: "Your Post Title Here"
date: 2026-05-28
description: "A short one-line description of your post (15 to 160 characters)."
draft: false
tags: ["tag1", "tag2", "tag3"]
aliases: ["A1"]
image: "/images/your-hero-image.jpg"
series: "minds-and-machines"
seriesOrder: "A1"
track: "A"
status: "published"
part: "Part I · The Dream"
figures: "Person One, Person Two, Person Three"
connects: "P2, A5, E1"
era: "Ancient – 1850"
---

Your amazing blog post content goes here...

Vault Note Template

---
title: "Your Note Title"
created: 2026-05-28
updated: 2026-05-28
author: Ishaan
description: "What this note is about."
publish: true
tags: [meta, research, notes]
order: 1
relatedChapters: "A5, P2, E1"
---

Your research note content goes here...

---

What Each Field Means

Required Fields (Your Post WILL NOT Build Without These)

Field	What to Write	Example
title	The name of your post (5–120 characters)	"The Ancient Dream of Artificial Life"
date	When this post is published (YYYY-MM-DD format)	2026-05-28
description	A short summary for search engines and previews (15–160 characters)	"From bronze giants to clockwork wonders..."

Series Fields (Only Needed if Your Post Belongs to a Series)

Field	What to Write	Example
series	Which series this post belongs to	"minds-and-machines"
seriesOrder	The chapter code within the series	"A1"
track	Which track: A (Articles), P (Profiles), or E (Events) — or any custom track you define	"A"
status	Publication status: published, upcoming, or planned — or any custom status you define	"published"
part	The act/part label	"Part I · The Dream"

Connection Fields (Help Link Posts Together)

Field	What to Write	Example
figures	Key people mentioned (comma-separated)	"Ada Lovelace, Alan Turing"
connects	Related chapter codes (comma-separated)	"P2, A5, E1"
era	The time period this post covers	"1936-1954"

Optional Fields

Field	What to Write	Example
draft	Is this a work-in-progress? Must be true or false	false
tags	A list of topic tags	["ai-history", "philosophy"]
aliases	A list of alias names for linking (must be a YAML list)	["A1"]
image	Hero image path (must start with /)	"/images/a1-hero.jpg"

---

Common Mistakes the Plugin Catches

The plugin checks your posts and shows you exactly what's wrong. Here are the most common problems:

Problem	What's Wrong	How to Fix
Missing title	No title field in frontmatter	Add title: "Your Title"
Missing date	No date field	Add date: 2026-05-28
Bad date format	Date is not in YYYY-MM-DD format	Use 2026-05-28 not May 28, 2026
Future date	Date is set in the future	Use a current or past date
Tags not a list	tags is a string instead of a list	Use ["tag1", "tag2"] not "tag1, tag2"
Aliases not a list	aliases is a string instead of a list	Use ["A1"] not "A1"
Has series but no order	series is set but seriesOrder is missing	Add seriesOrder: "A1"
Missing description	No description field	Add description: "Your description here"
Draft + published conflict	draft: true but status: "published"	Set draft: false or status: "upcoming"
Invalid track code	track is not one of your defined tracks	Use a track code from Settings
seriesOrder track mismatch	seriesOrder starts with a different track letter than track	Make them match
Profile missing figures	A Profile-track post has no figures field	Add figures: "Person Name"
Invalid connects reference	connects has references that don't match the track+number format	Use format like "A1, P5, E3"

---

Dashboard Features

Stats Bar

At the top of the dashboard, you'll see:

• Archive — Number of blog/archive posts
• Vault — Number of research notes
• Track counts — Posts per track (dynamic, from your settings)
• Drafts — Posts with draft: true
• Errors — Posts missing required fields
• Ready — Posts that pass all checks

Search and Filter

• Search box — Type to find posts by title, tag, era, figures, seriesOrder, or file path
• Filter buttons — Click to show only: All, Archive, track codes, Vault, Drafts, Recent, Errors
• Sort dropdown — Sort by Series Order, Newest, Oldest, Title A-Z, Errors First, Drafts First
• Search debounce — Search waits 200ms before filtering to keep things smooth

Card Actions

Each post card has buttons:

• Open — Opens the post in the editor
• Validate — Shows a quick summary of what's right or wrong
• Pre-flight — Marks a draft as ready for deployment (sets draft: false, status: "published", and today's date if none set)

Bulk Pre-flight

Click the Bulk pre-flight all drafts command to mark all drafts as ready for deployment. It will ask you to confirm first.

Right-click Context Menus

File explorer (right-click a file):

• Validate with isHistory — Check the post for errors
• Pre-flight with isHistory — Mark the post as ready for deployment
• Open in isHistory Dashboard — Jump to the dashboard

Editor (right-click inside a note):

• Validate this post — Check the post you're editing
• Pre-flight this post — Mark the current draft as ready

Status Bar

The status bar at the bottom of Obsidian shows your content health:

• "N ready" (green) — All posts are valid
• "N errors" (red) — Some posts have errors that need fixing
• "N warnings" (default) — Some posts have warnings
• Click the status bar to open the dashboard

---

Quick Validate Sidebar

This is a lightweight panel that shows you validation results for whatever post you're currently editing.

How to open it:

1. Press Ctrl+P (or Cmd+P on Mac)
2. Search for "Open quick validate"
3. The sidebar shows real-time validation as you type

---

Commands

You can access these from the command palette (Ctrl+P or Cmd+P):

Command	What It Does
Open isHistory dashboard	Opens the full content management dashboard
Open quick validate	Opens the sidebar validator
Validate current post	Checks the post you're editing for errors
Pre-flight current draft	Marks the draft you're editing as ready for deployment
New Articles (A-track)	Creates a new post for a track (one command per track)
Validate all content	Validates all content and shows summary
Bulk pre-flight all drafts	Marks all draft posts as ready for deployment

---

Deploying to Your Site

Pre-flighting a post marks it as ready for deployment, but doesn't push it live. To deploy changes to your Astro site:

1. Install Obsidian Git
2. Configure it to auto-commit and push on interval (e.g., every 5 minutes)
3. Your Astro site's CI/CD (Vercel, Netlify, Cloudflare Pages, etc.) detects the push and rebuilds automatically

That's the full pipeline: Write → Pre-flight → Git sync → Auto-deploy

You can also use any other Git sync method you prefer — the plugin only manages frontmatter, so any tool that commits and pushes your vault to your Astro repo will work.

Tip: You can also open Obsidian Git directly from the plugin's Settings page — there's a quick-access button at the bottom.

---

Settings

Go to Settings → isHistory CMS to configure:

Content Paths

• Archive path — Path to blog/archive content. Default: src/content/blog
• Vault path — Path to vault/research content. Default: src/content/vault
• Each path has a reset button to restore the default

Tracks

• Add, edit, or remove tracks with custom codes, names, emojis, and colors
• Each track gets its own "New post" command automatically
• Warning when deleting a track that has posts assigned to it
• Reset all tracks to defaults with one click

Post Statuses

• Add or remove publication statuses (e.g., published, upcoming, planned)
• Statuses appear as filter options and in pre-flight settings

Validation Rules

• Min/Max title length — Configurable thresholds for SEO compliance
• Min/Max description length — Meta description validation
• Image path must start with — Require hero images to start with / or another prefix
• Required archive fields — Add or remove fields that every archive post must have
• Cross-field validation — Warns when settings conflict (e.g., min > max, same paths)

Card Display

• Cards per page — How many cards before "Load More"
• Description preview length — Characters shown before truncation
• Figures preview length — Characters shown for figures field
• Tags shown per card — Maximum tags displayed
• Errors shown per card — Maximum errors displayed
• Tags in meta section — Maximum unique tags in the dashboard footer

New Post Template

• Default series — Series name applied to all new posts (e.g. minds-and-machines)
• Template variables — Use {{seriesOrder}}, {{trackName}}, {{date}}, etc.
• Slug format — File name pattern for new posts
• Title format — Default title for new posts
• Image path format — Hero image pattern
• Default status — Status for newly created posts
• Body template — Default content below the frontmatter

Pre-flight Settings

• Set draft flag to — What draft becomes when pre-flighting
• Set status to — What status becomes when pre-flighting
• Auto-fill today's date — Automatically fill in today's date if missing
• Reset all pre-flight settings to defaults with one click

Appearance

• Show ribbon icon — Toggle the isHistory dashboard icon in the left sidebar ribbon

Deploying to Your Site (in Settings)

• Quick-access button to open the Obsidian Git plugin settings (or its GitHub page if not installed)

Settings Validation

The settings page shows warnings when:

• Min length ≥ max length for any field
• No tracks or statuses are defined
• Archive path and vault path are the same

---

Version History

v1.7.0 — Mobile & Performance

• Mobile-Optimized Dashboard — Responsive layout that adapts to Obsidian Mobile and smaller screens
• Accessibility Improvements — ARIA labels on all interactive elements, keyboard-navigable controls, screen reader-friendly status badges
• Differential Rendering Engine — Fingerprint-based card updates that only re-render changed cards, not the entire dashboard
• YAML Shorthand Tolerance — Bare string tags and aliases (e.g. tags: ai-history instead of tags: [ai-history]) are now normalized without errors
• Boundary-Aware Path Detection — Prevents false collection matches (e.g. src/content/blog-vault/ no longer matches the archive path src/content/blog)
• Connects Cross-Reference Validation — Warns when connects references don't follow the track+number format (e.g. A1, P5, E3)
• Future Date Warning — Flags posts with publication dates set in the future
• Comprehensive Test Suite — Full unit test coverage for validation, caching, sorting, and filtering with Vitest
• Auto Settings Migration — Seamless upgrade from any previous version; deep-merge preserves all user settings

v1.6.0 — Trust & Workflow

• Pre-flight Validation Gate — Warns about errors before publishing
• Track Deletion Warning — Shows how many posts use a track before deleting
• Failed Save Notice — Alerts when settings can't be saved
• Cross-field Settings Validation — Catches conflicting settings
• Deep-merge Settings — Safe upgrades without data loss
• Status Bar Health Indicator — Content health at a glance
• Sort Options Dropdown — Six sort modes in the dashboard
• Recently Modified Filter — Posts edited in the last 24 hours
• Right-click Context Menus — Quick actions on files
• Search Debounce (200ms) — Smooth search performance

v1.5.0 — Settings That Make Sense

• Full settings UX overhaul (no more sliders)
• Dynamic track system with custom codes, emojis, and colors
• Template engine with variable substitution
• Chip editors for statuses and required fields
• Color pickers and reset buttons

v1.4.0 — Your Tracks, Your Way

• Dynamic track system — create any track type
• Color-coded tracks in dashboard and stats
• Regex-based scanning derived from track codes

v1.3.0 — The Big Picture

• Dashboard view for browsing all posts
• Search, filter, and stats bar
• Pagination with "Load More"

v1.2.0 — Side by Side

• Sidebar view for real-time validation
• Auto-updates when switching files

v1.1.0 — Bug Squashing

• Fixed plugin freeze on file open
• Fixed sidebar not updating
• Fixed floating promise errors

v1.0.0 — The Beginning

• Initial release with frontmatter validation
• Basic pre-flight and status management
• Dashboard view and status bar

---

FAQ

The dashboard shows "No content found"

Make sure your Archive path or Vault path in settings matches where your content actually is. If your posts are in src/content/blog/, the archive path should be src/content/blog.

BRAT says "frozen" next to my plugin version

That's normal! In BRAT, "(frozen)" just means the plugin is pinned to a specific version. It does NOT mean the plugin is broken. Your plugin is working fine.

How do I update the plugin?

Community Store: Settings → Community Plugins → Click "Check for updates" → Update Manual: Download the latest release files and replace the old ones. BRAT: BRAT settings → Check for updates → Update.

The plugin is slow with many posts

Go to Settings → isHistory CMS and lower the Cards per page number. Try 20 instead of 40.

I clicked Pre-flight but my site didn't update

Pre-flight only changes frontmatter in your vault. You still need to sync your vault to Git (using Obsidian Git or another tool) for your Astro site to rebuild and deploy. See the Deploying to Your Site section above.

Will updating the plugin delete my settings?

No! The plugin uses a deep-merge strategy that reads your existing settings, keeps everything you configured, and only adds any new fields that didn't exist before. Your settings are always safe.

Do I need to know regex to use custom tracks?

No! The default settings work great out of the box. Regex is only used internally to match seriesOrder patterns based on your track codes. You just pick a short code (like "A", "P", "E") and the plugin handles the rest.

---

Built For

This plugin is designed for the isHistory Astro project — a deep-dive into the history of Artificial Intelligence. It uses:

• Astro with Content Collections
• Two content collections: archive (blog posts) and vault (research notes)
• Series system: Articles (A), Profiles (P), Events (E) — each organized into tracks

But it works with any Astro project that uses content collections!

---

Security

• Release assets are built via GitHub Actions with artifact attestations for main.js and styles.css (cryptographic provenance verification)
• No innerHTML usage — DOM manipulation uses Obsidian's createEl API (with two minimal document.createElement calls for style injection and card rendering)
• No !important in CSS — proper selector specificity is used instead
• No builtin-modules npm dependency — uses Node.js built-in module.builtinModules
• Vault scanning uses app.vault.getMarkdownFiles() — the recommended Obsidian API that only accesses markdown files, not all vault files

---

Requirements

• Obsidian v1.0.0 or later
• An Astro project with Content Collections

---

Development

# Install dependencies
npm ci

# Build for production
npm run build

# Development mode (watch)
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

---

License

MIT