Krems lets you publish Markdown websites to Github pages.

☕️ Buy me a coffee ☕️

1. Fork the example site
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.

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 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.

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.

There are two page types.

• 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 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
---

• 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"]
---

• 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"

1. Download the latest binary and put it in your path
2. Create a Krems site or clone the 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

The example has a Workflow that uses the Krems Github 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

• about Krems static site generation
• about the Krems Obsidian plugin
• about the Krems Github Action