Kaspa Notes — Web Site Context

Kaspa Notes is an educational documentation site for the Kaspa blockchain. Covers technical deep dives (covenants, vProgs, ZK, PSKT), ecosystem directory, glossary, and interactive RPC tools. Built and maintained by Charles Vallone (GitHub: smartgoo).

Live site: https://www.kaspanotes.com

Obsidian Context

File	Purpose
`c-Areas/Kaspa Notes 𐤊.md`	Area note — next actions, incubation backlog
`d-Resources/Crypto/Kaspa/Resources.md`	Kaspa learning resources and reference links
`d-Resources/Crypto/Kaspa/Glossary.md`	Glossary terms and structure notes
`d-Resources/Kaspa Notes - Web/`	This directory — Obsidian mirror of site pages (synced to SvelteKit)

Always check c-Areas/Kaspa Notes 𐤊.md for current priorities.

Local Repository

Path: ~/projects/kaspa-notes
GitHub: https://github.com/smartgoo/kaspa-notes (private)
Main branch: main

Tech Stack

Layer	Details
Framework	SvelteKit + Svelte 5
Content	mdsvex (Markdown in Svelte) for page content
Styling	Tailwind CSS 4, `@tailwindcss/typography`
Icons	Lucide Svelte
SEO	Custom `SEO.svelte` component, `super-sitemap`, rehype plugins (slug, autolink-headings, external-links)
Hosting	Vercel (adapter-vercel)
Analytics	Vercel Analytics
Linting	ESLint + Prettier (with svelte and tailwind plugins)

Commands

npm run dev        # Local dev server
npm run build      # Production build
npm run preview    # Preview production build
npm run lint       # Check formatting (prettier + eslint)
npm run format     # Auto-format with prettier

Project Structure

src/
├── app.html
├── app.css
├── lib/
│   ├── components/       # Reusable Svelte components
│   │   ├── RpcCall.svelte       # Interactive RPC tool
│   │   ├── CodeTabs.svelte      # Multi-language code blocks
│   │   ├── TableOfContents.svelte
│   │   ├── SEO.svelte
│   │   └── ...
│   ├── kaspa/            # Kaspa-specific logic
│   │   ├── rpc/          # RPC client
│   │   ├── rpc-methods.js
│   │   └── full/         # Full node connection utils
│   ├── links.js          # Auto-generated sidebar nav (from sync script)
│   ├── utils/
│   └── highlighter.js    # Syntax highlighting config
├── routes/
│   ├── ecosystem/        # Ecosystem directory
│   │   ├── cross-chain/
│   │   ├── explorers-&-analytics/
│   │   ├── l1-protocols/
│   │   ├── l2/
│   │   │   ├── igra-labs/
│   │   │   └── kasplex/
│   │   ├── news-sources-&-hubs/
│   │   ├── organizations/
│   │   └── wallets/
│   ├── resources/        # Technical docs & reference
│   │   ├── covenants++/
│   │   ├── developer-resources/
│   │   ├── glossary/
│   │   ├── phantom-ghostdag/
│   │   ├── pskt-&-pskb/
│   │   ├── silverscript/
│   │   ├── vprogs/
│   │   └── zero-knowledge/
│   ├── tools/            # Interactive tools
│   │   ├── rpc-calls/
│   │   └── rpc-subscriptions/
│   ├── new-&-noteworthy/
│   ├── llms.txt/
│   └── sitemap.xml/
static/                   # Static assets

Content pages use .svx (mdsvex) files — Markdown with embedded Svelte components.

Obsidian → SvelteKit Sync

Site content is authored in Obsidian at d-Resources/Kaspa Notes - Web/ and synced to SvelteKit via sync-from-obsidian.py in the repo root.

How it works

Each .md file under Kaspa Notes - Web/ maps to a SvelteKit route
Route is derived entirely from the file’s relative path: lowercase, spaces → hyphens
The script reads YAML frontmatter (title, description, updated) and body
It wraps the body in Svelte boilerplate (SEO, MdPageHeader, TableOfContents)
Writes to src/routes/{route}/+page.svx
Generates src/lib/links.js — sidebar navigation data used by +layout.svelte

Obsidian file structure

Kaspa Notes - Web/
├── Home.md                          → src/routes/+page.svx (raw, no boilerplate)
├── ecosystem/
│   ├── Cross Chain.md              → ecosystem/cross-chain/
│   ├── Explorers & Analytics.md    → ecosystem/explorers-&-analytics/
│   ├── L1 Protocols.md             → ecosystem/l1-protocols/
│   ├── News Sources & Hubs.md      → ecosystem/news-sources-&-hubs/
│   ├── Organizations.md            → ecosystem/organizations/
│   ├── Wallets.md                  → ecosystem/wallets/
│   └── l2/
│       ├── Igra Labs.md            → ecosystem/l2/igra-labs/
│       └── Kasplex.md              → ecosystem/l2/kasplex/
├── resources/
│   ├── covenants++/
│   │   ├── Opcodes.md              → resources/covenants++/opcodes/
│   │   └── Overview.md             → resources/covenants++/overview/
│   ├── Developer Resources.md      → resources/developer-resources/
│   ├── Glossary.md                 → resources/glossary/
│   ├── PHANTOM GHOSTDAG.md         → resources/phantom-ghostdag/
│   ├── PSKT & PSKB.md             → resources/pskt-&-pskb/
│   ├── SilverScript.md             → resources/silverscript/
│   ├── VProgs.md                   → resources/vprogs/
│   └── Zero Knowledge.md           → resources/zero-knowledge/
└── tools/
    ├── RPC Calls.md                → skipped (skip_sync: true)
    └── RPC Subscriptions.md        → rpc-subscriptions/

Content format

Each .md file has YAML frontmatter + pure markdown. Dates use YYYY-MM-DD format and are localized client-side by FormattedDate.svelte.

---
title: Page Title
description: One-line description.
updated: 2026-01-24
nav_title: Custom Label
---

Body content here...

Field	Required	Purpose
`title`	Yes	Page title (used in SEO and header)
`description`	Yes	One-line description
`updated`	Yes	Last updated date (YYYY-MM-DD)
`nav_title`	No	Override label in sidebar (defaults to `title`)
`nav_hidden`	No	Set to `true` to exclude from sidebar nav
`skip_sync`	No	Set to `true` to skip syncing this file

Sidebar nav section is inferred from the top-level directory under Kaspa Notes - Web/ (e.g., ecosystem/ → “Ecosystem”, resources/ → “Resources”). Root-level files appear without a section header. Links are sorted alphabetically within each section.

Workflow

1. Write/edit in Obsidian
2. Run: python3 sync-from-obsidian.py
3. git diff to review
4. Commit & push → Vercel deploys

Infrastructure

Component	Details
Frontend	Vercel (auto-deploys from `main`)
RPC proxy	`rpc.kaspanotes.com` — proxies to Kaspa node, behind Cloudflare
Kaspa node	Runs on OVH VPS (shared with Kaspalytics infra)

Git Workflow

Always pull latest from main before starting work
Always develop in a feature branch — never commit directly to main
Merge feature branch back to main for deployment — Vercel auto-deploys on merge

Maintenance

At the start of any session involving Kaspa Notes Web, verify this file is accurate:

Repo path, branch, and tech stack match reality
Site routes and content structure are current
Obsidian note references still exist

Flag any drift and offer to update before proceeding.