@karaoke-cms/astro

v0.18.1

Published

2 days ago

Core Astro integration for karaoke-cms — virtual config, wikilinks, handbook routes

0High
0Medium
0Low

krishanm

astro cms obsidian astro-integration

@karaoke-cms/astro

Core Astro integration for karaoke-cms. Wires up themes, modules, collections, menus, Obsidian embed handling, and the virtual config module at build time. Every karaoke-cms project depends on this package.

Installation

npm install @karaoke-cms/astro

Usage

// astro.config.mjs
import { defineConfig } from 'astro/config';
import karaoke from '@karaoke-cms/astro';
import karaokeConfig from './karaoke.config.ts';

export default defineConfig({
  site: 'https://your-site.pages.dev',
  integrations: [karaoke(karaokeConfig)],
});

// karaoke.config.ts
import { defineConfig } from '@karaoke-cms/astro';
import { loadEnv } from '@karaoke-cms/astro/env';
import { blog } from '@karaoke-cms/module-blog';
import { docs } from '@karaoke-cms/module-docs';
import { themeDefault } from '@karaoke-cms/theme-default';

const env = loadEnv(new URL('.', import.meta.url));

export default defineConfig({
  vault: env.KARAOKE_VAULT,
  title: 'My Site',
  description: 'What this site is about.',
  theme: themeDefault(),
  modules: [blog({ mount: '/blog' }), docs({ mount: '/docs' })],
});

Configuration

All fields are optional. Defaults produce a working site with no content.

| Field | Type | Default | Description | |-------|------|---------|-------------| | vault | string | project root | Path to the Obsidian vault directory (absolute or relative) | | title | string | 'Karaoke' | Site title for browser tab and nav | | description | string | '' | Site description for RSS and OG tags | | theme | ThemeInstance | — | Theme from themeDefault() or similar | | modules | ModuleInstance[] | [] | Additional modules not covered by the theme | | comments | CommentsConfig | — | Giscus comments config | | collections | Record<string, CollectionConfig> | — | Per-collection mode overrides | | layout.regions | { top, left, right, bottom } | — | Region component lists |

Obsidian embed syntax

Markdown files can use Obsidian's ![[file]] embed syntax. The integration handles it automatically:

Image embeds

![[photo.jpg]]           — embedded image (Astro-optimized)
![[photo.jpg|300]]       — image with width hint → <img width="300">
![[photo.jpg|300x200]]   — image with width and height → <img width="300" height="200">
![[photo.jpg|alt text]]  — image with alt text

Image files are resolved in this order:

Same folder as the note
Vault attachmentFolderPath from .obsidian/app.json
Vault root

Resolved images go through Astro's image optimisation pipeline.

Audio and video embeds

![[recording.mp3]]   — → <audio controls>
![[clip.mp4]]        — → <video controls>

Audio and video files are served from /media/ in dev and copied to dist/media/ at build time.

Wiki links in `featured_image` frontmatter

featured_image: "[[hero.jpg]]"

The wiki link is resolved using the same vault path lookup as inline embeds and rewritten to /media/hero.jpg. Use resolveWikiImage() in your templates — see below.

`resolveWikiImage(value)`

A utility for templates that render featured_image. Call it on the raw frontmatter value — it rewrites [[file.jpg]] to /media/file.jpg and passes regular paths and URLs through unchanged.

import { resolveWikiImage } from '@karaoke-cms/astro';

// In an Astro template:
<img src={resolveWikiImage(entry.data.featured_image)} alt={entry.data.title} />

This is necessary because Astro sets entry.data from validated frontmatter at collection-load time, before the remark plugin runs. Templates must call resolveWikiImage() to get the resolved URL.

Exports