Skip to content

quickstart.md

Latest commit

 

History

History
182 lines (129 loc) · 3.5 KB

quickstart.md

File metadata and controls

182 lines (129 loc) · 3.5 KB

Quickstart

This guide uses the static yiipress binary. It is the recommended way to use YiiPress because it includes the PHP runtime and native extensions.

1. Create a site directory

mkdir myblog
cd myblog

Download the YiiPress binary from the latest GitHub release or workflow artifact and place it in this directory as yiipress (yiipress.exe on Windows):

cp /path/to/yiipress ./yiipress
chmod +x ./yiipress

On Windows, use yiipress.exe in the examples below.

2. Create the initial files

Run:

./yiipress init

This creates content/config.yaml, content/navigation.yaml, and two starter collections. Edit content/config.yaml:

title: My Blog
description: A personal blog
base_url: https://example.com
languages: [en]

date_format: "F j, Y"
entries_per_page: 10

permalink: /:collection/:slug/

taxonomies:
  - tags
  - categories

3. Review collections

yiipress init creates a page collection for standalone pages and a blog collection for dated posts:

content/
├── page/
│   └── _collection.yaml
└── blog/
    └── _collection.yaml

4. Write your first post

Create the post with the scaffold command:

./yiipress new "Hello World" --collection=blog

Then edit the generated file in content/blog/. A typical post looks like this:

---
title: "Hello World"
tags:
  - general
---

Welcome to my blog! This is my first post.

## What is YiiPress?

YiiPress is a static blog engine built on [Yii3](https://yiisoft.github.io/docs/guide/intro/what-is-yii.html). It is:

- Exceptionally fast
- File-based (no database)
- Extensible with plugins

5. Create a page

Use the same command without --collection for a root-level page:

./yiipress new "About"

A simple content/about.md page looks like this:

---
title: "About"
---

This is my personal blog where I write about programming.

6. Add navigation

Edit content/navigation.yaml:

main:
  - title: Home
    url: /
  - title: Blog
    url: /blog/
  - title: About
    url: /about/

7. Build the site

./yiipress build

This generates static HTML in the output/ directory:

output/
├── blog/
│   ├── feed.xml
│   ├── hello-world/
│   │   └── index.html
│   ├── rss.xml
│   └── index.html
├── about/
│   └── index.html
├── tags/
│   ├── general/
│   │   └── index.html
│   └── index.html
└── sitemap.xml

8. Preview locally

Start the dev server:

./yiipress serve

Open the URL printed by the command. The preview server rebuilds after content changes and refreshes the browser.

Build options

Include drafts and future-dated posts during development:

./yiipress build --drafts --future

Use multiple workers for faster builds:

./yiipress build --workers=4

By default, YiiPress uses --workers=auto, which detects available CPU capacity and uses up to 4 workers automatically.

Disable cache for a clean build:

./yiipress build --no-cache

Next steps

  • Add authors in content/authors/ — see Content
  • Customize permalinks — see Content
  • Configure markdown extensions — see Configuration
  • Link between posts using relative .md paths — see Content
  • Learn about all build options — see Commands