Karaoke

Quick start for Obsidian users

This guide is for people who use Obsidian and want to put some notes on the internet. You don’t need to know TypeScript or how Astro works. You do need to open a terminal a few times.

Step 1: Install Node.js

Node.js is the runtime that builds your site. Go to nodejs.org and download the LTS version (22 or later). Run the installer. That’s it.

To confirm it worked, open a terminal and run:

node --version

You should see something like v22.x.x.

Step 2: Create your project

In your terminal, run:

npm create @karaoke-cms@latest my-site

When it asks questions, press Enter to accept the defaults. Then:

cd my-site
npm install

This may take a minute. It’s downloading everything the site builder needs.

Step 3: What got created

Your my-site folder now looks roughly like this:

my-site/
  karaoke-website-vault/   ← your vault — this is where you write notes
    blog/                  ← blog posts go here
    docs/                  ← documentation pages go here
    _website/              ← nav config and page templates — you rarely need to touch this
  karaoke.config.ts        ← site settings (title, modules, theme)
  .env.default             ← tells the framework where your vault is
  astro.config.mjs         ← Astro config — you don't need to touch this
  package.json             ← project metadata — you don't need to touch this

The most important folder is karaoke-website-vault/. That’s your Obsidian vault.

Step 4: Open the vault in Obsidian

In Obsidian, choose Open folder as vault and select the karaoke-website-vault folder inside your project. You can now write notes in Obsidian and they’ll feed directly into your site.

You can also open the my-site folder as a vault if you want to see the whole project in Obsidian, but opening just the vault folder keeps things cleaner.

Step 5: Write your first note

Inside Obsidian (or any text editor), create a file at karaoke-website-vault/blog/hello.md and add this at the top:

---
title: "Hello from my site"
publish: true
date: 2024-01-01
description: "My first published note."
---

This note will appear on my site because I added `publish: true` at the top.

The section between the --- lines is called frontmatter. It’s just metadata. The only field that controls whether a note is public is publish: true. Without it, the note stays private.

Step 6: Understand .env.default

Open .env.default in any text editor. It contains one line:

KARAOKE_VAULT=./karaoke-website-vault/

This tells the framework where your vault folder is. You don’t need to understand this file. Just know that if you ever rename your vault folder, you’ll need to update this line to match.

Step 7: Preview your site locally

In your terminal, from the my-site folder, run:

npm run dev

Open http://localhost:4321 in your browser. You should see your site with your first blog post. Press Ctrl+C to stop the server when you’re done.

Step 8: Push to GitHub

GitHub stores your site’s code and triggers automatic deploys whenever you save changes.

If you’re comfortable with the terminal:

git add .
git commit -m "My first site"
git remote add origin https://github.com/your-username/my-site.git
git push -u origin main

If you prefer a visual tool, GitHub Desktop is free and works well. Create a new repository from your my-site folder, then publish it.

Step 9: Deploy to Cloudflare Pages

Cloudflare Pages hosts your site for free and rebuilds it every time you push to GitHub.

  1. Go to dash.cloudflare.com and sign up or log in (free).
  2. In the sidebar, click Workers & Pages, then Create, then Pages.
  3. Click Connect to Git and authorize Cloudflare to access your GitHub account.
  4. Select your my-site repository.
  5. On the build settings screen, fill in:
    • Build command: npm run build
    • Build output directory: apps/website/dist
  6. Under Environment variables, add:
    • Name: KARAOKE_VAULT, Value: ./karaoke-website-vault/
  7. Click Save and Deploy.

After about two minutes your site will be live at a URL like my-site.pages.dev. Every time you push new notes to GitHub, the site rebuilds automatically.

What you should see

  • Your blog post at your-site.pages.dev/blog/hello
  • A tag index at /tags
  • A search page at /search

Notes without publish: true will never appear anywhere. karaoke-cms checks this automatically on every build.

What to do next

  • Write more notes. Add publish: true to the ones you want public.
  • Read Core concepts to understand how the vault, privacy, and modules fit together.
  • Look at karaoke.config.ts to change your site title, description, or add new features.