Pushpin

GitHub

Getting Started

Installation
Overview

Concepts

Pages
Templates
Sections
CLI

Deployment

GitHub Pages

Overview

Pushpin is a static site generator focused on simplicity. Write site content in Markdown, style with Tera HTML templates, and Pushpin compiles the site to HTML. There are tons of similar and inspiring static site generators, to name a few:

Quick tour

We'll walk through creating a new site, building it, and examining its structure. Then we'll add a new page and template.

Create and examine a new site

After installing Pushpin, generate a site:

$ pushpin init my-new-site
📌 success: initialized new site 'my-new-site'

my-new-site will contain this directory structure:

- pages/
    - index.md
    - posts/example_post.md
- templates/
    - index.html
    - post.html
- style/
    - style.css

In my-new-site, generate the site and serve it with a local server:

$ cd my-new-site
$ pushpin serve --watch
📌 success: generated site; created 8 files
📌 local server available at http://127.0.0.1:7878
🔍 Watching for changes in 'pages/', 'templates/', (type Ctrl+C to stop):

The --watch flag is optional; when supplied, Pushpin will automatically re-run when you update any content or template.

Pushpin generates HTML files for each Markdown file in pages/ in the site root directory. Similar to SSGs like Zola, the directory structure of the output is based on the structure of the Markdown files.

- pages/
    - index.md
    - posts/example-post.md
- templates/
    - index.html
    - post.html
- style/
    - style.css

# Newly generated:
- index.html
- posts/
  - example-post.html

This is the primary local development flow. When you deploy, you'll likely use pushpin generate to generate the site files, instead of pushpin serve.

Add a new page and template

Create a new directory in pages/ called example-section, and add a Markdown file called example-page.md inside. Add a new template for it called page.html:

- pages/
    - index.md
    - posts/example_post.md
    - example-section/ # New section
      - example-page.md # New page in the new section
- templates/
    - index.html
    - post.html
    - page.html # New template for example-page.md
- style/
    - style.css
- index.html
- pages/
  - example-post.html

By adding a directory in pages/, we have created a Section, one way to organize site pages.

Write some content in example-page.md. Associate it with its template with Frontmatter:

---
template: page.html
---

# Example page header

This is an example page.

Add this code for the template:

<!DOCTYPE html>
<html>
  <head></head>
  <body>
  {{ content | safe}}
  </body>
</html>

Run pushpin serve. The Markdown content is compiled to HTML, and then inserted into templates via content | safe.

Finally, navigate to http://127.0.0.1:7878/example-section/example-page.html to see the generated page.

We've created a site, examined its structure, and we added a new page. This is the primary development loop. To learn more about each concept, check out the rest of the Concepts, as well as Deployment.