✨ Live Demo: corkboard.hyperfluid.tech
A skeuomorphic blog platform built with Rust. Write Markdown files, and Corkboard turns them into a fully styled website that looks and feels like paper notes pinned to a cork board.
- Zero friction: Drop
.mdfiles into a folder and run. No database, no build step, no JavaScript framework. - Rich Markdown: Syntax-highlighted code blocks, chalkboard-styled tables, footnotes, task lists, and image cards — all out of the box.
- Tactile design: WebGL paper textures, procedural torn-paper edges, pushpin decorations, and highlighter-pen title effects.
- Open-source & Self-hostable: Freely fork, customize, and run your own deployment via Docker or Cargo.
- Getting Started
- Writing Articles
- Tech Stack
- Configuration
- Contributing
- Testing (Golden Tests)
- License
Corkboard is available in two Docker image variants:
- Default/Lean Variant (
gilnobrega/corkboard:latest): A lightweight image designed only for loading local Markdown files. - Git-Enabled Variant (
gilnobrega/corkboard:latest-git): A variant compiled with the Git feature to automatically pull articles from a remote Git repository.
Create a docker-compose.yml file using your preferred variant (e.g., the lean version):
version: '3.8'
services:
corkboard:
image: gilnobrega/corkboard:latest
container_name: corkboard_blog
restart: unless-stopped
ports:
- "8080:3000"
volumes:
- ./articles:/app/articles
- ./assets:/app/assets
environment:
- PUID=1000
- PGID=1000
- CORKBOARD_BLOG_TITLE=My blog
- CORKBOARD_BLOG_AUTHOR=Author
- CORKBOARD_BASE_URL=http://your-domain-here.com:8080Then start the service:
docker-compose up -dOnce the container is up, navigate to http://localhost:8080 in your browser.
The articles directory will be created if it does not exist, and a welcome post will be generated automatically. You can configure any setting using environment variables prefixed with CORKBOARD_. For more advanced control, see the reference docker/docker-compose.yml.
Requires Rust and Cargo and Node.js and NPM installed on your machine.
First, install the frontend dependencies and compile the Tailwind CSS stylesheet:
npm install
npm run build:cssThen run the application (defaults to local-only files):
cargo runIf you want to run the application with the Git data source enabled:
cargo run --features gitIf you are modifying HTML templates or styles, you can run the CSS compiler in watch mode in a separate terminal:
npm run watch:cssOnce running, navigate to http://localhost:3000 in your browser.
Place Markdown files inside the articles/ directory. Each file needs a YAML frontmatter block:
---
title: "My First Post"
date: "2026-01-15"
description: "An optional description shown below the title"
thumbnail: "/assets/my-thumbnail.webp"
---
Your content goes here. Standard Markdown is supported:
**bold**, *italic*, `inline code`, lists, tables, images,
footnotes, and fenced code blocks with syntax highlighting.Articles are sorted by date (newest first) and displayed on a single scrollable page. Long articles are truncated with a "Read more" link to their dedicated page.
You can reference local images and files from your articles by placing them in the assets/ directory at the project root (or /app/assets inside a Docker container).
Reference assets in your Markdown using the /assets/ path prefix:
---
title: "My Post with Images"
date: "2026-01-15"
thumbnail: "/assets/my-thumbnail.webp"
---
Here is a photo from my local assets folder:
You can also organize assets into subdirectories:
assets/
├── photos/
│ ├── sunset.jpg
│ └── portrait.png
├── diagrams/
│ └── architecture.svg
└── my-thumbnail.webp
Security note: Only asset files that are explicitly referenced in your Markdown articles (via
image syntax or thethumbnailfrontmatter field) will be served. Any file placed inassets/that is not referenced by an article will return a403 Forbiddenresponse. This prevents accidental exposure of unreferenced files.
- Rust (Axum): Fast, async HTTP routing.
- Askama: Strongly-typed, compiled HTML templates.
- Syntect: Server-side syntax highlighting for fenced code blocks.
- Pulldown-cmark: CommonMark-compliant Markdown parsing with extensions.
- WebGL: Procedural paper texture shader for realistic card surfaces.
All settings live in config.toml at the project root:
blog_title = "My blog"
blog_author = "Author"
blog_license = "CC 4.0 BY-SA"
blog_license_url = "https://creativecommons.org/licenses/by-sa/4.0/"
base_url = "https://your-domain-here.com"
articles_dir = "articles"
port = 3000
truncate_lines = 15
preview_include_images = false
thumbnail_show_articles = false
# social_links = [
# "https://github.com/your-username",
# "https://linkedin.com/in/your-username",
# "https://twitter.com/your-username"
# ]
# cors_allowed_origins = ["http://localhost:3000"]
# csp_allowed_origins = [
# "http://localhost:3000",
# "https://fonts.googleapis.com",
# "https://fonts.gstatic.com"
# ]
# [git]
# link = "https://github.com/user/repo"
# folder = ""
# username = "user"
# password = "pat"
# branch = "main"Every setting can be configured via a config.toml file or overridden using an environment variable prefixed with CORKBOARD_. For nested configuration fields like git, the environment variable should use a double underscore separator (__), for example: CORKBOARD_GIT__LINK.
Advanced Configuration & Environment Variables
| Setting | Environment Variable | Default | Description |
|---|---|---|---|
blog_title |
CORKBOARD_BLOG_TITLE |
My blog |
Shown in the header and page title |
blog_author |
CORKBOARD_BLOG_AUTHOR |
Author |
Shown in the footer copyright |
blog_license |
CORKBOARD_BLOG_LICENSE |
CC 4.0 BY-SA |
License name in the footer |
blog_license_url |
CORKBOARD_BLOG_LICENSE_URL |
(CC link) | URL the license links to |
base_url |
CORKBOARD_BASE_URL |
https://your-domain-here.com |
The public/external URL of the blog (used for RSS, sitemaps, social cards) |
articles_dir |
CORKBOARD_ARTICLES_DIR |
articles |
Directory to scan for .md files |
port |
CORKBOARD_PORT |
3000 |
Internal HTTP port the application listens on |
truncate_lines |
CORKBOARD_TRUNCATE_LINES |
15 |
Markdown lines shown per card before truncation |
preview_include_images |
CORKBOARD_PREVIEW_INCLUDE_IMAGES |
false |
Whether to include images in truncated article previews |
thumbnail_show_articles |
CORKBOARD_THUMBNAIL_SHOW_ARTICLES |
false |
Whether to show article snippets in the blog's generated thumbnail |
social_links |
CORKBOARD_SOCIAL_LINKS |
(empty list) | List of social/external URLs to show in the footer (comma-separated in env) |
cors_allowed_origins |
CORKBOARD_CORS_ALLOWED_ORIGINS |
[base_url] |
List of allowed CORS origins. Defaults to the configured base_url. (comma-separated list in env) |
csp_allowed_origins |
CORKBOARD_CSP_ALLOWED_ORIGINS |
(base_url + Google Fonts) | List of allowed CSP origins. Defaults to base_url + Google Fonts. If left unmodified, external asset origins referenced in markdown articles (images/thumbnails) are dynamically allowed. (comma-separated list in env) |
[!NOTE] These settings require building with the
gitfeature (e.g.cargo run --features git), or using thelatest-gitDocker image.
| Setting | Environment Variable | Default | Description |
|---|---|---|---|
git.link |
CORKBOARD_GIT__LINK |
(none) | Git repository HTTPS/SSH URL to clone and load remote articles from |
git.folder |
CORKBOARD_GIT__FOLDER |
"" |
Subfolder within the git repository containing articles (defaults to root) |
git.assets_folder |
CORKBOARD_GIT__ASSETS_FOLDER |
"" |
Subfolder within the git repository containing assets to be copied to the local assets folder |
git.username |
CORKBOARD_GIT__USERNAME |
(none) | Optional username for basic auth (only needed if not public repository) |
git.password |
CORKBOARD_GIT__PASSWORD |
(none) | Optional password or PAT (Personal Access Token) for authenticated access |
git.branch |
CORKBOARD_GIT__BRANCH |
main |
Target git branch name to check out |
Contributions are always welcome! Whether it's a bug report, a new feature, or a typo fix, feel free to open an issue or submit a pull request.
Please see TESTING.md for guidelines on how to run and update the visual regression tests when changing layout or styling elements.
This project is licensed under the MPL 2.0 License.
The paper texture shader (templates/paper-shader.js) is adapted from @paper-design/shaders under the PolyForm Shield License 1.0.0.