Quick Start Guide

For: Anyone who has never run Kukui and wants to see a site locally and deploy it.

In this guide you'll: Install dependencies and config, start the dev server, add a post, build the static site, and deploy to S3/CloudFront or rsync. You'll also know where to look when something goes wrong.

Your path from zero to live

Prerequisites

• Node.js 20 or higher
• npm or yarn
• Your content in an obsidian folder (or use the skeleton that ships with the repo)

Installation

1. Install dependencies:

   npm install

2. First-time setup (no site yet): Run the wizard. It creates system-config.json, sites.json, and provisions a new site from the skeleton:

   yarn wizard

   If you already have a site: ensure system-config.json (project root) has siteRoot pointing to your sites directory, and that sites.json (under that root) has your site ID and sites entries.

Development

1. Start the development server:

   yarn dev

   You'll get an interactive menu to select which site to run (or use --site <siteId>). Open http://localhost:3000 in your browser.

2. Optional — auto-regenerate on file changes: In a second terminal, run:

   yarn watch

   The watcher regenerates navigation, album indexes, and other data when you change markdown, images, or config.

Adding content

1. Create a new .md file in the right folder under your site's obsidian directory.

2. Add frontmatter at the top:

   ---
   slug: my-first-post
   title: My First Post
   description: A short description for listings and SEO
   tags: [intro, example]
   ---

3. Use wikilinks to link to other notes: [[Page Name]] or [[Folder/Page Name]].

4. Embed a YouTube video with: <Youtube id="VIDEO_ID" title="Video Title" />.

Live example:

For full content options (frontmatter, directives, albums, playlists), see Authors-Guide.

Building for production

1. Build the static site:

   yarn build

   The site is written to a site-specific out directory (path comes from sites.json for your site ID).

2. Preview the build locally (optional):

   yarn preview

Deployment

Default: AWS S3 + CloudFront. Alternative: rsync to an EC2 or other server.

Option 1: Deploy to S3/CloudFront (default)

1. In sites.json, set for your site: s3.bucket, s3.region, and cloudfront.distributionId. (S3 target is read from sites.json only — no .env needed for the bucket.)

2. Run:

   yarn deploy

   This builds (if needed), syncs the out directory to S3, and invalidates the CloudFront cache.

Option 2: Deploy via rsync (EC2 or traditional server)

1. In sites.json, set rsync.host for your site (e.g. user@host.example.com:/path), or set DEPLOY_HOST in .env.

2. Run:

   yarn deploy-rsync

Option 3: Manual

After yarn build, upload the contents of the out directory to any static host (Netlify, Vercel, GitHub Pages, etc.).

For full deployment options, verification, and CI/CD, see Deployment-Guide.

Project structure (short)

Config lives at project root (system-config.json) and under the site root (sites.json, and per-site content.json).

Tips

• Edit markdown in the obsidian folder; the dev server and watcher pick up changes.
• Routes are generated from your folder structure and frontmatter slug.
• Use yarn wizard anytime for a guided menu of common tasks.

Something not working? See Troubleshooting for build, styles, and deployment issues.

Next steps

• Write and structure content: Authors-Guide
• Configure and extend: Developers-Reference
• Deploy and automate: Deployment-Guide
• Fix problems: Troubleshooting