---
title: "Pages - Minimal Static Site Generator"
description: "minimal static site generator built on deno and markdown"
---

# pages

minimal static site generator for a personal site. built on deno, markdown, and
a tiny amount of custom glue.

source: https://github.com/rnbguy/pages

## quick start

no need to clone the tool repo.

1. **create your site**

   ```bash
   deno run -A jsr:@rnbguy/pages init my-site
   cd my-site
   ```

   this creates `my-site/` with git, a starter `src/index.md`, and
   `config.yaml`.

2. **update config**

   edit `config.yaml` with your details:
   ```yaml
   title: your site name
   url: https://yourusername.github.io/your-repo
   github: yourusername
   # optional: add twitter, image, etc.
   ```

   > [!NOTE]
   >
   > if this repo is your `username.github.io` repository, use
   > `username.github.io` as your url

3. **build and preview**

   ```bash
   deno run -A jsr:@rnbguy/pages build
   deno run -A jsr:@rnbguy/pages serve
   ```

   open http://localhost:8000

4. **deploy to github pages**

   commit and push your site directory. then go to your repo on github. click on
   "settings" tab and then "pages", and then set "source" to "github actions".

   see [deployment](/deploy) for a full github actions workflow.

   > [!NOTE]
   >
   > if you intend to (or already) use a custom domain for github pages, use
   > `thatwebsite.com/repo-name` or just `thatwebsite.com` accordingly

## install globally

to avoid typing `deno run -A jsr:@rnbguy/pages` every time, install it as a
global command:

```bash
deno install -g -A jsr:@rnbguy/pages
```

then use `pages` directly:

```bash
pages init my-site
cd my-site
pages build
pages serve
```

to update:

```bash
deno install -g -A -rf jsr:@rnbguy/pages
```

see [deno install](https://docs.deno.com/runtime/reference/cli/install/) for
setting up your PATH.

## commands

```bash
pages init <name>     # create a new site project
pages build            # generate the site
pages serve            # local preview server
pages new              # scaffold a new page
pages build --help     # see all options
```

## structure

after running `init`, your site directory looks like:

    src/          # markdown + static assets (default, configurable)
    dist/         # build output (after build)
    config.yaml   # site settings
    .gitignore    # ignores dist/

> [!NOTE]
>
> this tool's own repo uses `src: pages` in its `config.yaml` because `src/`
> contains the deno source code. the default source directory for users is
> `src/`.

## learn more

- [features](/features) - what pages can do
- [markdown](/markdown) - frontmatter, mermaid, code blocks, alerts
- [configuration](/config) - config.yaml reference
- [deployment](/deploy) - github pages setup

---

> [!WARNING]
>
> this project contains code generated by llm models.