Project Awesome project awesome
♥

SkunkHTML

Markdown blog with GitHub Pages.

Package 167 stars GitHub

GitHub repo size GitHub License GitHub Created At GitHub forks GitHub Repo stars

SkunkHTML

The simplest way to run a blog on GitHub Pages.

Fork this repo (or use it as a template). Enable GitHub Pages. You have a blog. That's it.

SkunkHTML

No CLI to install. No config files to learn. No build tools on your machine. Write Markdown, push to GitHub, your site updates automatically.

See it in action: Live demo

Get started in 60 seconds

  1. Fork this repository
  2. Go to Settings > Pages > Source: GitHub Actions
  3. Your blog is live at https://YOUR-USERNAME.github.io/skunk-html/

To publish a post: add a Markdown file to the markdown-blog/ folder. The file name is the date - name it like 2025-03-24.md and start the file with a # Title heading. The title comes from the heading, the date comes from the file name. Push. Done.

Features

  • Zero local setup - everything runs on GitHub Actions
  • Markdown -> HTML - write in Markdown, get a clean website
  • RSS feed - your readers can subscribe (/feed.xml)
  • Sitemap - search engines find your content (/sitemap.xml)
  • SEO meta tags - Open Graph and Twitter Cards out of the box
  • Dark mode - respects your visitors' system preference automatically
  • Themes - choose from built-in color themes or tweak CSS variables
  • Comments - optional Giscus integration
  • Syntax highlighting - code blocks are highlighted automatically
  • No dependencies on your machine - no Node.js, no Ruby, no Go

Customize your site

Edit SkunkUtils.fs - you only need to change the values in quotes:

let siteTitle = "My Blog"
let siteDescription = "A blog powered by SkunkHTML"
let siteBaseUrl = "https://YOUR-USERNAME.github.io/skunk-html"  // No trailing slash
let siteLanguage = "en"
let siteAuthor = "Your Name"

You don't need to know F# - just edit the text between the quotation marks.

Base URL examples - set siteBaseUrl to match where your site is hosted:

  • GitHub project page: https://YOUR-USERNAME.github.io/skunk-html
  • GitHub user page (repo named <user>.github.io): https://YOUR-USERNAME.github.io
  • Custom domain: https://example.com
  • Self-hosted with subpath: https://example.com/blog

Themes

SkunkHTML ships with multiple color themes. To switch themes, copy the contents of a theme file from themes/ into css/tweaks.css:

Theme File Style
Default css/tweaks.css Clean, minimal with dark mode
Ocean themes/theme-ocean.css Cool blue tones (GitHub-inspired)
Terminal themes/theme-terminal.css Green-on-dark hacker aesthetic
Ink themes/theme-ink.css Warm serif typography (newspaper-inspired)

All themes respect prefers-color-scheme - they look great in both light and dark mode.

Content structure

  • Blog posts: Markdown files in markdown-blog/ whose names start with a digit. The file name is the publication date (e.g. 2025-03-24.md). The post title comes from the first # Heading inside the file.
  • Other pages: Markdown files in markdown-blog/ that don't start with a digit (e.g. about.md, featured.md)
  • Front page: markdown-blog/index.md - optional welcome content displayed above the post list

HTML fragments

Customize the header, footer, and page head by editing files in html/:

  • header.html - site navigation and logo
  • footer.html - footer content
  • head.html - meta tags, CSS links, and favicons
  • script_giscus.html - Giscus comments configuration

Folder structure

skunk-html/
├── .github/workflows/    # GitHub Actions build & deploy
├── assets/               # Avatar, favicon, shared resources
├── css/                  # Stylesheets (styles.css + tweaks.css)
├── fonts/                # Custom fonts
├── html/                 # HTML fragments (header, footer, head)
├── markdown-blog/        # Your content goes here
│   └── images/           # Images used in articles
├── scripts/              # Syntax highlighting script
├── themes/               # Alternative color themes
├── SkunkUtils.fs          # Configuration and utilities
├── SkunkHtml.fs           # HTML generation engine
├── Program.fs             # Build entry point
└── skunk-html.fsproj      # F# project file

Optional: build locally

You don't need this for normal use - GitHub Actions handles everything. But if you want to preview locally:

git clone https://github.com/mg0x7BE/skunk-html.git
cd skunk-html
dotnet restore
dotnet run

Your site will be in skunk-html-output/. Requires .NET.

How it works

When you push a Markdown file to markdown-blog/, GitHub Actions runs a small F# program that converts your Markdown to HTML using FSharp.Formatting, generates RSS and sitemap, wraps everything in a clean layout based on MVP.css, and deploys to GitHub Pages.

The entire build engine is ~400 lines of F#. No frameworks. No plugins. No magic.

Contributing

Suggestions, bug reports, and pull requests welcome. Use discussions, issues, or PRs.

License

Unlicense - do whatever you want with it.

Dependencies

Back to F#