Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kk0x03/kip) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: your@email.com
---

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.

Push code to GitHub
Go to repo Settings → Pages, select "GitHub Actions"
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

@kk0x03/kip