6 stable releases
1.2.0 | Aug 20, 2024 |
---|---|
1.1.1 | Aug 12, 2024 |
1.0.2 | Jul 16, 2024 |
#136 in Template engine
368 downloads per month
25KB
319 lines
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:
- You can optionally add a title and meta_description in front-matter. This
will be used in the
meta
tags for the page. - 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
Dependencies
~9–18MB
~249K SLoC