✨ 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.
.md files into a folder and run. No database, no build step, no JavaScript framework.Corkboard is available in two Docker image variants:
gilnobrega/corkboard:latest): A lightweight image designed only for loading local Markdown files.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:8080
Then start the service:
docker-compose up -d
Once 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:css
Then run the application (defaults to local-only files):
cargo run
If you want to run the application with the Git data source enabled:
cargo run --features git
If you are modifying HTML templates or styles, you can run the CSS compiler in watch mode in a separate terminal:
npm run watch:css
Once 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.
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.
| 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 `git` feature (e.g. `cargo run --features git`), or using the `latest-git` Docker 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.
Content type
Image
Digest
sha256:65ee77a85…
Size
323.4 MB
Last updated
3 months ago
docker pull gilnobrega/corkboard