npm package: @kk0x03/kip
Description: A simple, minimal blog framework for showcasing your projects
Author: kk0x03
Latest version: 2.3.5

# 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

```bash
# 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:

```yaml
# 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`:

```markdown
---
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/`:

```markdown
---
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:

```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:

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

```bash
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

```bash
kip theme list
```

### Switch Theme

```bash
kip theme use dark
kip theme use light
```

### Create Custom Theme

```bash
kip theme create my-theme
```

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

## Local Development

```bash
# 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](https://umami.is/) analytics by configuring in `_config.yml`:

```yaml
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](https://github.com/kk0x03/kip)
- npm: [@kk0x03/kip](https://www.npmjs.com/package/@kk0x03/kip)