Kip

A minimal blog framework for showcasing your projects. Built with React + Vite + TypeScript, deploy to GitHub Pages with one command.

Features

• Simple & Clean - Just profile + project list, focus on content
• Markdown Driven - Write in Markdown with frontmatter support
• Theme System - Install and customize themes
• Notion Integration - Sync content from Notion pages
• Separate Deployment - Keep content private, deploy site publicly
• CLI Tool - Simple commands for dev, build, deploy

Quick Start

# Install globally
npm install -g @kk0x03/kip

# Create new project
kip init my-portfolio

# Enter directory
cd my-portfolio

# Start dev server
kip dev

# Build and deploy
kip build
kip deploy

Project Structure

A Kip project only needs two parts:

my-portfolio/
├── blog/
│   ├── profile.md        # Your profile
│   ├── images/           # Image assets
│   │   └── avatar.png
│   └── projects/         # Project articles
│       ├── project-1.md
│       └── project-2.md
└── _config.yml           # Site configuration

CLI Commands

| Command | Description | |---------|-------------| | kip init <name> | Create new project | | kip dev | Start development server | | kip build | Build for production | | kip deploy | Build and deploy to GitHub | | kip theme list | List installed themes | | kip theme use <name> | Switch theme | | kip help | Show help message |

Configuration

Edit _config.yml to configure your site:

# Site info
title: My Portfolio

# Theme: dark | light
theme: dark

# Deploy config (optional)
deploy:
  repo: https://github.com/username/username.github.io.git
  branch: main

Profile

Edit blog/profile.md:

---
name: Your Name
bio: A short introduction
avatar: /images/avatar.png
social:
  github: https://github.com/yourusername
  email: [email protected]
---

Write a longer introduction here...

Projects

Create Markdown files in blog/projects/:

---
title: Project Name
description: Brief description
date: 2024-01-01
tags:
  - React
  - TypeScript
image: /images/project-screenshot.png
link: https://github.com/user/repo    # Optional, external link
order: 1                               # Optional, sort order
draft: false                           # Optional, hide from list
---

## Introduction

Detailed project description...

## Features

- Feature 1
- Feature 2

## Screenshot

![Screenshot](/images/screenshot.png)

Field Reference

| Field | Required | Description | |-------|----------|-------------| | title | Yes | Project name | | description | No | Brief description, shown in list | | date | No | Date | | tags | No | Array of tags | | image | No | Cover image path | | link | No | External link, shown on detail page | | order | No | Sort order, lower numbers first | | draft | No | Set true to hide from list |

Images

Place images in blog/images/:

blog/
└── images/
    ├── avatar.png
    ├── project-1.png
    └── screenshot.gif

Use /images/ path in Markdown:

# In frontmatter
image: /images/project-1.png

# In content
![Description](/images/screenshot.gif)

Deployment

Deploy to Separate Repository

Keep your blog content in a private repo, deploy the site to a public GitHub Pages repo:

# _config.yml
deploy:
  repo: https://github.com/username/username.github.io.git
  branch: main

kip deploy

Deploy to Same Repository

Use GitHub Actions for automatic deployment. The project includes .github/workflows/deploy.yml.

1. Push code to GitHub
2. Go to repo Settings → Pages, select "GitHub Actions"
3. Auto-deploys on every push

Themes

List Themes

kip theme list

Switch Theme

kip theme use dark
kip theme use light

Create Custom Theme

kip theme create my-theme

Customize styles and components in themes/my-theme/.

Local Development

# Clone repo
git clone https://github.com/kk0x03/kip.git
cd kip

# Install dependencies
npm install

# Start dev server
npm run dev

# Link globally (for CLI testing)
npm link

Analytics (Umami)

Add Umami analytics by configuring in _config.yml:

umami:
  website_id: your-website-id
  src: https://cloud.umami.is/script.js  # or your self-hosted URL

A visitor counter will appear in the footer showing "You are visitor #xxx".

Tech Stack

• React 19 - UI framework
• Vite 7 - Build tool
• TypeScript 5 - Type safety
• React Router 7 - Client-side routing
• marked - Markdown parsing
• gray-matter - Frontmatter parsing

License

MIT

Links

• GitHub: https://github.com/kk0x03/kip
• npm: @kk0x03/kip