Getting Started

Requirements: Python 3.11+

InkStone works with any Markdown editor — even a plain text editor. For the full experience (wiki-links, Dataview, callouts, transclusions), use Obsidian. Foam (VS Code) is the closest alternative with compatible syntax.

Running locally

git clone https://github.com/airenare/inkstone
cd inkstone

pip install -r requirements.txt

# Point at your vault (or omit to use the bundled demo vault)
echo "VAULT_PATH=/path/to/your/vault" > .env

python3 app.py
# → http://127.0.0.1:8000

The server hot-reloads when vault files change. No restart needed.

Docker

Mount a local vault directory:

docker build -t inkstone .
docker run -p 8000:8000 -v /path/to/vault:/vault inkstone

Or use docker-compose.yml with a .env file to clone a private vault repo at build time — see Deployment for details.

If /vault is not mounted or doesn't exist, the server falls back to the bundled BlogPages/ demo vault.

Publishing your first note

Add website: true to a note's frontmatter:

---
website: true
title: My First Post
date: 2026-01-15
tags:
  - hello
---

Your content here.

The note is now live. Its URL is derived from its folder path and title.

Vault structure basics

See Features for the full frontmatter reference.

Frontmatter reference

---
website: true         # required to publish
type: homepage        # homepage | listing | book
title: My Post        # overrides H1 and filename
date: 2026-01-15
slug: my-post         # auto-generated from title if omitted
summary: "..."        # shown on listing cards; auto-derived if omitted
featured: true        # highlight in the section's featured area
priority: 0           # featured posts: lower = higher rank
menu_order: 1         # pin to top nav; lower = further left
show_search: true     # root homepage only: adds Search to nav
show_tags: true       # root homepage only: adds Tags to nav
language: en          # root homepage only: sets the site language
default_theme: dark   # root homepage only: initial theme for new visitors — dark | light | system
github: https://github.com/you       # social links — one key per platform
mastodon: https://mastodon.social/@you
banner: "https://example.com/image.jpg"
banner_x: 0.5         # focal point 0–1
banner_y: 0.4
author: "Jane Doe"
updated: 2026-04-01   # shown as "Updated …" in post meta
icon: _attachments/logo.png  # image beside the site title; cascades to child pages
site_title: "My Brand"       # replaces the website name in the header; cascades to child pages
language: en          # root homepage only: default site language ("en", "ru", "fr", etc.)
lang: ru              # per-note: marks this note as a language variant; also set by _RU.md suffix
tags:
  - python
  - philosophy
aliases:
  - alternate name
---

title: "From Vault to Web: How This Works"   # correct
title: From Vault to Web: How This Works      # broken