mksite

Turn your Markdown files into a beautiful website.

Write in Markdown → Run one command → Get a website ready to publish.

---

Quick Start

Step 1: Install Rust

If you don't have Rust installed, open your terminal and run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then restart your terminal.

Step 2: Build the tool

In this project folder, run:

cargo build --release

This creates the mksite program.

Step 3: Generate your website

./target/release/mksite build

Your website is now in the dist folder!

---

How It Works

pages/                    dist/
├── home.md          →    ├── index.html           (homepage)
├── about.md         →    ├── about/index.html     (nav link)
└── blogs/           →    └── blogs/
    ├── post-1.md              ├── index.html      (listing page with cards)
    └── post-2.md              ├── post-1/index.html
                               └── post-2/index.html

Simple files like about.md become direct pages.

Folders like blogs/ get a special listing page that shows all posts inside as cards.

---

Configuration

All settings live in site.yaml in your project root:

name: "My Site"
footer: "Built with [mksite](https://github.com)"

pagination: 10

nav:
  - about
  - blogs

Settings Explained

Setting	What it does	Example
name	Your site's name (shows in header and browser tab)	"John's Blog"
footer	Footer text (supports markdown links)	"Made by [Me](https://example.com)"
pagination	How many items per page in listing pages	10
nav	Which pages/folders appear in navigation	[about, blogs, contact]

Navigation Rules

The nav list controls what appears in your navigation bar:

• Single files (like about.md) → Link directly to that page
• Folders (like blogs/) → Link to a listing page showing all posts inside

Example:

nav:
  - about      # links to /about/ (single page)
  - blogs      # links to /blogs/ (listing of all blog posts)
  - projects   # links to /projects/ (listing of all projects)
  - contact    # links to /contact/ (single page)

---

Writing Pages

Every page needs a header section called "frontmatter" at the top:

---
title: My Page Title
date: 2025-12-17
tags: [one, two, three]
description: A short description for SEO
---

Your content goes here...

Frontmatter Fields

Field	Required?	What it does
title	Yes	The page title
date	No	Shows a date badge (great for blog posts)
tags	No	Adds colorful badges
description	No	Shows on listing cards + used by search engines

Writing Content

Use normal Markdown:

# Big Heading
## Smaller Heading

This is a paragraph with **bold** and *italic* text.

- Bullet point
- Another point

1. Numbered list
2. Second item

> This is a quote

`inline code` or code blocks with triple backticks

---

Folder Structure

your-site/
├── site.yaml        ← Your site configuration
├── pages/           ← Put your Markdown files here
│   ├── home.md      ← This becomes your homepage (/)
│   ├── about.md     ← This becomes /about/
│   └── blogs/       ← Folder = listing page + individual posts
│       ├── post-1.md
│       └── post-2.md
├── dist/            ← Your generated website (deploy this)
└── src/             ← Source code (don't touch)

---

Commands

Build your site

./target/release/mksite build

Create a new page

./target/release/mksite new "My New Page"

This creates pages/my-new-page.md with the frontmatter already set up.

---

Listing Pages

When you have a folder in pages/ (like blogs/), mksite automatically creates a listing page.

The listing page shows:

• All posts as clickable cards
• Title, date, description, and tags for each post
• Pagination (if you have more than 10 posts)

Posts are sorted by date, newest first.

Pagination

If you have many posts, they'll be split across pages:

/blogs/           ← Page 1 (first 10 posts)
/blogs/page/2/    ← Page 2
/blogs/page/3/    ← Page 3

Change how many posts per page in site.yaml:

pagination: 5   # Show 5 posts per page instead of 10

---

Mobile Support

The site automatically adapts to mobile screens:

• Navigation becomes a hamburger menu
• Content adjusts to smaller screens
• Cards stack vertically

No configuration needed!

---

Dark Mode

The site automatically switches between light and dark mode based on your system settings.

No configuration needed!

---

Publishing Your Site

Option 1: Netlify (Recommended)

1. Go to netlify.com and sign up
2. Click "Add new site" → "Deploy manually"
3. Drag and drop your dist folder
4. Done! You get a free URL like your-site.netlify.app

Option 2: Vercel

1. Go to vercel.com and sign up
2. Click "Add New" → "Project"
3. Upload your dist folder
4. Done!

Option 3: GitHub Pages

1. Create a GitHub repository
2. Upload the contents of your dist folder
3. Go to Settings → Pages → Enable GitHub Pages
4. Your site is live at username.github.io/repo-name

---

Troubleshooting

"Config file not found"

Make sure you have a site.yaml file in your project root.

"command not found"

Use the full path to the program:

./target/release/mksite build

"File must start with frontmatter"

Every .md file needs to start with:

---
title: Something
---

Changes not showing up

Run the build command again:

./target/release/mksite build

Navigation not showing my page

Make sure the page/folder is listed in the nav section of site.yaml:

nav:
  - about
  - blogs
  - your-new-page

---

Tips

• Preview locally: Open dist/index.html in your browser
• Add images: Put images in dist/ and reference them with ![](image.png)
• Homepage: The file named home.md (or index.md) becomes your homepage
• Descriptions: Add descriptions to your posts—they show up on the cards!

---

MIT License - Copyright (c) 2024 - @mksite