https://github.com/mreider/krems
A static site generator (SSG) written in Ruby
https://github.com/mreider/krems
Last synced: 6 months ago
JSON representation
A static site generator (SSG) written in Ruby
- Host: GitHub
- URL: https://github.com/mreider/krems
- Owner: mreider
- Created: 2024-12-05T16:56:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-01T20:23:50.000Z (about 1 year ago)
- Last Synced: 2025-01-01T21:27:22.697Z (about 1 year ago)
- Language: HTML
- Homepage:
- Size: 600 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-static-generators - Krems - A simple, lightweight static site generator for Markdown, with live preview, and GitHub Pages compatibility. `#Ruby` (Uncategorized / Uncategorized)
README
# Krems
Krems lets you publish Markdown websites to Github pages.
[☕️ Buy me a coffee ☕️](https://coff.ee/mreider)
## Getting started
1. Fork the [example site](https://github.com/mreider/krems-example/)
2. Enable the workflow
3. Turn on Github Pages in the repository
- Push from the gh-pages branch
- Use the /(root) folder
4. View your repository's actions
- An action should be running
- When it's done your website will be ready
You can view your website in a browser.
For example:
https://your-gh-user.github.io/krems-example/
Note: The config.yaml file contains my example URL, so links will redirect to that URL instead of yours. To fix this, edit your local config.yaml file and redeploy.
## Learn from the example and build your own site
The example site shows all of the functionality of Krems. The default CSS works out-of-the-box. If you want to improve it, open a pull request back at the [Krems](https://github.com/mreider/krems) repository and I can update it.
See the config.yaml section (further down the readme) to see how to include your own CSS, JS, and Favicons. CSS must work with standard Bootstrap HTML classes, which you can see [here](https://codepen.io/matthew-reider/pen/dPoOebJ).
## Images
You must store your images in an /images folder and reference them using normal markdown. You can have subfolders of images to keep them organized.
## Page Types
There are two page types.
## List pages
- show links to other pages
- only show pages that have dates
- (usually) have no markdown content
- (usually) show a list of pages in a single directory
- (usually) exist as index.md in a directory
- have the following front matter:
```
---
title: "Krems Home Page"
type: list
created: 2025-06-04T09:24
updated: 2025-06-04T09:39
---
```
## List page filters
List page filters expand the functionality of a list page
- shows all pages in all subdirectories with:
- specific tags (or...)
- specific authors
- have the following front matter:
```
---
title: Krems Home Page
type: list
tagFilter:
- about
authorFilter:
- Matt
---
```
## Default pages
- have Markdown content
- include an (optional) image
- is converted to an Open Graph image
- displayed as a preview images when someone shares the page URL
- have the following frontmatter:
```
---
title: "Krems City Info"
date: "2024-11-26"
image: "/images/krems1.png"
author: "Matt"
tags: ["about"]
---
```
## About config.yaml
- required at root directory
- must have `basePath` if home page is in a subdirectory
- must have `devPath` to run locally without subdirectory
- supports alternative CSS, JS, and favicon paths to override defaults
- follows example below:
```
website:
url: "https://mreider.github.io/krems-example"
name: "Krems Example Site"
basePath: "/krems-example"
devPath: "/"
alternativeCSSDir: "path/to/your/css" # Optional: Directory for your CSS files
alternativeJSDir: "path/to/your/js" # Optional: Directory for your JS files
alternativeFavicon: "path/to/your/favicon.ico" # Optional: Path to your favicon file
menu:
- title: "Home"
path: "index.md"
- title: "Universities"
path: "universities/index.md"
```
## Running Krems locally
1. Download the [latest binary](https://github.com/mreider/krems/releases) and put it in your path
2. Create a Krems site or clone the [example](https://github.com/mreider/krems-example)
3. Run and browse the site:
- `krems --run`
- runs at localhost:8080 (--port to override)
4. this creates a .tmp directory with HTML
5. clean the .tmp directory using:
- `krems --clean`
6. to build the site without running:
- `krems --build`
## About the Github Action
The [example](https://github.com/mreider/krems-example) has a Workflow that uses the [Krems Github Action](https://github.com/mreider/krems-deploy-action).
- Generates the site on push
- Commits the website to gh-pages branch using the /(root) directory
- Creates a CNAME file if the config.yaml has a custom domain
## Questions / feedback
- [about Krems static site generation](https://github.com/mreider/krems/issues)
- [about the Krems Obsidian plugin](https://github.com/mreider/krems-obsidian-plugin/issues)
- [about the Krems Github Action](https://github.com/mreider/krems-deploy-action/issues)