cliché

A dead simple static site generator. ¯\_(ツ)_/¯

Features

• All Markdown
• File based routing
• Add an optional header and footer to all pages
• Add an optional stylesheet

Does that list seem short? Good. That's the idea. If it takes you longer to figure out how to use this thing than it does to write your own SSG then I failed.

No templating. No automatic aggregation of links on pages. No themes.

Based on the premise that curation is valuable, so you'll need to manually organize and link your pages. It's really not that hard with a decent text editor.

Install

Install Rust then run:

cargo install cliche  

Usage

Usage: cliche [OPTIONS] <CONTENT>

Arguments:
  <CONTENT>  Directory containing the site's content

Options:
      --header <HEADER>      Path to the site's header [default: header.md]
      --footer <FOOTER>      Path to the site's footer [default: footer.md]
      --style <STYLE>        Path to the site's stylesheet [default: style.css]
  -o, --output <OUTPUT>      Site output directory. Will be created if it doesn't already exist [default: _site]
      --domain <DOMAIN>      The domain of the site, used for generating full URLs in the sitemap. If not provided, a sitemap will not be generated
      --base-url <BASE_URL>  A base url that the site will be served from
  -h, --help                 Print help
  -V, --version              Print version

Details

Add a header file (optional)

<!-- header.md -->

# my awesome website

<nav>

[home](contents/index.md)
[about](contents/about.md)
[whatever](contents/a/secret/path/whatever.md)

</nav>

Add a footer file (optional)

<!-- footer.md -->

[Contact](fake@gmail.com) | [Github](https://github.com/gdtroszak/cliche)

Add some content

Create a directory for your content and add some files to it. Here's an example that shows the URL paths to each page.

.
└── content/
    ├── index.md              /
    ├── static/
    │   └── image.jpg         /static/image.jpg
    ├── food/
    │   ├── index.md          /food
    │   ├── coffee.md         /food/coffee.html
    │   └── bread/
    │       ├── sourdough.md  /food/bread/sourdough.html
    │       └── wheat.md      /food/bread/wheat.html
    └── bikes/
        └── gravel.md         /bikes/gravel.html

Maybe I'd want my homepage to link to a few other pages.

<!-- content/index.md -->

---
title: my amazing website
meta_description: a website about me and all the things I like.
---

- [food](./food/index.md)
- [gravel biking](content/bikes/gravel.md)

A few things to note here:

1. You can optionally add a title and meta_description in front-matter. This will be used in the meta tags for the page.
2. Links to other content can either be relative to the file itself or the root of your project. Use a text editor with a Markdown LSP. It'll make this really easy.

Add some style (optional)

/*style.css */

html {
    ...
}

body {
    ...
}

I'd recommend that you just copy one of the many classless options available.

You can add classes by throwing a bunch of HTML all over your Markdown, but that probably won't end well.

Run it

cliche ./content

Your site should get spit out to a _site directory. If you took advantage of using index.md's to generate more canonical URL paths, you'll need to serve the site. Something like simple-http-server is perfect for that.

simple-http-server -i --nocache ./_site

Want more?

See my personal website for an example.

GitHub Action

If you'd like to automate the generation and deployment of your site using GitHub Actions, you can use the cliche-action. This action runs cliche and creates an artifact that you can deploy to your prefered hosting provider. Here's an example workflow that deploys a site to GitHub Pages.

name: deploy to pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: false
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: checkout
        uses: actions/checkout@v4
      - name: build site and upload artifact
        uses: gdtroszak/cliche-action@v1
      - name: setup pages
        uses: actions/configure-pages@v5
      - name: deploy to gh pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          artifact_name: cliche-site