bamboo 🎋

A fast static site generator written in Rust.

Live Demo · cargo install bamboo-cli

Bamboo transforms markdown content with frontmatter into static HTML sites. It features syntax highlighting, Tera templating, live reload development, shortcodes, asset optimization, responsive images, and generates RSS/Atom feeds, sitemaps, and search indexes automatically.

Features

Quick Start

cargo install bamboo-cli
bamboo new my-site
cd my-site
bamboo serve

Open http://localhost:3000 to see your site. Edit files and watch them rebuild instantly.

Template

Use the bamboo-template for a ready-to-deploy starter with GitHub Pages CI included.

CLI Commands

bamboo new <name>              # Create a new site in a new directory
bamboo init                    # Initialize a site in the current directory
bamboo build                   # Build the site to dist/
bamboo build --drafts          # Include draft content
bamboo build --theme ./mytheme # Use a custom theme
bamboo build --output ./public # Custom output directory
bamboo build --base-url <url>  # Override base URL
bamboo serve                   # Dev server with live reload at localhost:3000
bamboo serve --port 8080       # Custom port
bamboo serve --open            # Open browser automatically
bamboo serve --drafts          # Include drafts in dev server

Project Structure

my-site/
├── bamboo.toml              # Site configuration
├── content/
│   ├── _index.md            # Home page
│   ├── about.md             # Static page → /about/
│   ├── docs/                # Nested pages
│   │   └── _index.md        # → /docs/
│   ├── posts/               # Blog posts → /posts/<slug>/
│   │   └── 2024-01-15-hello.md
│   └── projects/            # Collection (needs _collection.toml)
│       ├── _collection.toml
│       ├── my-project.md
│       └── archived/        # Nested subdirectories supported
│           └── old-project.md
├── data/                    # Data files accessible in templates
│   └── nav.toml             # → {{ site.data.nav }}
├── static/                  # Copied as-is to output
│   └── images/
└── templates/               # Site-level template overrides
    └── shortcodes/          # Custom shortcode templates

Configuration

bamboo.toml:

title = "My Site"
base_url = "https://example.com"
description = "A site built with Bamboo"
author = "Your Name"
language = "en"
posts_per_page = 10    # Posts per page (0 = all on one page)
syntax_theme = "base16-ocean.dark"  # Syntax highlighting theme
math = false           # Enable LaTeX math rendering
minify = false         # Minify CSS, JS, and HTML output
fingerprint = false    # Content-hash asset filenames for cache busting
link_check_ignore = []  # Paths the link validator treats as external (e.g. ["/other-project"])

[taxonomies.tags]      # Built-in (auto-configured)
singular = "tag"

[taxonomies.categories]  # Built-in (auto-configured)
singular = "category"

[images]               # Responsive image generation (optional)
widths = [320, 640, 1024, 1920]
quality = 80
formats = ["webp", "jpg"]

[extra]
github = "https://github.com/username"

All [extra] fields are available in templates as {{ site.config.extra.github }}.

Content

Frontmatter

TOML style:

+++
title = "My Post"
date = "2024-01-15"
tags = ["rust", "web"]
categories = ["tutorials"]
draft = false
weight = 10
template = "custom.html"
excerpt = "Custom excerpt text"
redirect_from = ["/old-url/"]
+++

Your content here...

YAML style:

---
title: My Post
date: 2024-01-15
tags:
  - rust
  - web
---

Your content here...

Frontmatter Fields

Date from Filename

Posts can embed dates in filenames: 2024-01-15-hello-world.md extracts date 2024-01-15 and slug hello-world.

Nested Pages

Pages can be organized in subdirectories. Use _index.md for directory index pages:

• content/docs/_index.md → /docs/
• content/docs/getting-started.md → /docs/getting-started/

Shortcodes

Shortcodes embed reusable components in markdown content.

Inline Shortcodes

{{</* youtube id="dQw4w9WgXcQ" */>}}
{{</* figure src="/images/photo.jpg" caption="A photo" */>}}
{{</* gist user="username" id="abc123" */>}}
{{</* pdf src="/resume.pdf" title="Resume" */>}}
{{</* pdf src="/resume.pdf" embed="true" height="800" */>}}

Block Shortcodes

Block shortcodes wrap markdown content:

{{%/* note type="warning" title="Heads up" */%}}
This content is rendered as **markdown** inside the shortcode.
{{%/* /note */%}}

{{%/* details summary="Click to expand" */%}}
Hidden content here.
{{%/* /details */%}}

Built-in Shortcodes

Custom Shortcodes

Place Tera HTML templates in templates/shortcodes/. Parameters become template variables:

<!-- templates/shortcodes/alert.html -->
<div class="alert alert-{{ level }}">{{ body }}</div>

{{%/* alert level="danger" */%}}
Something went wrong!
{{%/* /alert */%}}

Shortcode templates also receive a base_url variable matching site.config.base_url. Use it to resolve author-provided local paths so content works correctly when deployed under a subpath:

<!-- templates/shortcodes/download.html -->
{% if src is starting_with("http") %}
  {% set resolved = src %}
{% else %}
  {% set resolved = base_url ~ src %}
{% endif %}
<a href="{{ resolved | safe }}" download>{{ label | default(value="Download") }}</a>

Templating

Bamboo uses Tera for templating. Templates live in your theme's templates/ directory. Site-level templates in templates/ override theme templates.

Template Context

All templates receive:

Index template (index.html):

Post template (post.html):

Page template (page.html):

Tag/Category page templates (tag.html, category.html):

Collection templates (collection.html, collection_item.html):

Custom Filters

Template Example

{% extends "base.html" %}

{% block content %}
<article>
  <h1>{{ post.title }}</h1>
  <time>{{ post.date | date(format="%B %d, %Y") }}</time>
  <span>{{ post.reading_time }} min read</span>

  <div class="tags">
    {% for tag in post.tags %}
    <a href="{{ site.config.base_url }}/tags/{{ tag | slugify }}/">{{ tag }}</a>
    {% endfor %}
  </div>

  {{ post.content | safe }}
</article>
{% endblock %}

Data Files

Place TOML, YAML, or JSON files in data/. They're accessible as site.data.<filename>.

# data/social.toml
[[links]]
name = "GitHub"
url = "https://github.com/username"

[[links]]
name = "Twitter"
url = "https://twitter.com/username"

<!-- In template -->
{% for link in site.data.social.links %}
<a href="{{ link.url }}">{{ link.name }}</a>
{% endfor %}

Nested directories work: data/nav/main.toml → site.data.nav.main

Themes

Bamboo includes a built-in default theme with light/dark mode toggle. Create custom themes by specifying a theme directory:

bamboo build --theme ./my-theme

Theme Structure

my-theme/
├── templates/
│   ├── base.html
│   ├── index.html
│   ├── page.html
│   ├── post.html
│   ├── collection.html
│   ├── collection_item.html
│   ├── tags.html
│   ├── tag.html
│   ├── categories.html
│   ├── category.html
│   ├── pagination.html
│   ├── search.html
│   ├── 404.html
│   ├── shortcodes/
│   │   └── *.html
│   └── partials/
│       ├── header.html
│       ├── footer.html
│       └── nav.html
└── static/
    └── css/

Theme Overrides

Override specific templates without creating a full theme by placing templates in your site's templates/ directory. These take priority over theme templates.

Examples

The repository includes example sites:

Portfolio Template

Set template = "portfolio.html" in content/_index.md to use the built-in portfolio layout. Every section is optional, and each one only renders if its data source is present.

Config fields (all under [extra] in bamboo.toml):

Local paths (anything not starting with http, https, or //) are automatically prefixed with site.config.base_url.

Data files (under data/):

Blog Layout (Author Profile Sidebar)

The default index.html, post.html, and page.html templates render with a sticky two-column author profile sidebar when [extra.author_profile] is set. When the field is absent the layout falls back to single-column (no breakage for existing sites).

[extra.author_profile]
name = "Jane Doe"
avatar = "/bio-photo.jpg"   # local path or full URL
bio = "Writing about distributed systems and compression."

[[extra.author_profile.links]]
label = "Email"
url = "mailto:jane@example.com"
icon = "envelope"

[[extra.author_profile.links]]
label = "GitHub"
url = "https://github.com/jane"
icon = "github"

[[extra.author_profile.links]]
label = "RSS"
url = "/rss.xml"
icon = "rss"

Supported icon values: envelope / email / mail, github, linkedin, twitter / x, mastodon, rss, website / globe / link. Unknown or omitted icon falls back to a generic link glyph.

Post Features

post.html composes a set of slot partials. Each slot is opt-out via [extra] toggles (default true):

Feature image is set per-post via frontmatter:

+++
title = "My Post"
tags = ["rust"]

[extra]
image = "/images/header.jpg"
image_alt = "A descriptive alt text"
image_caption = "Optional caption"
+++

Local paths are prefixed with site.config.base_url automatically. The image also becomes the og:image meta tag for social share cards.

Edit-on-GitHub link is enabled globally by setting extra.edit_url_base to your repo's edit URL. The link resolves to {edit_url_base}/content/posts/{slug}.md unless overridden by extra.source_path in the post frontmatter.

Social Meta Tags

Open Graph and Twitter Card meta tags are emitted on every page automatically. The og:image / twitter:image chooses, in order:

1. Per-post extra.image
2. Per-page extra.image
3. Site-wide extra.og_image
4. Author profile avatar (extra.author_profile.avatar)

Optional: set extra.twitter_handle = "@yoursite" to attribute the card.

Posts-by-Year Archive

Create content/archive.md (or any path) with the archive template:

+++
title = "Archive"
template = "archive.html"
+++

Every post, grouped by year.

The template iterates site.posts and groups entries by year. The author-profile sidebar renders alongside if configured.

Grouped Category / Tag Archives

For a Jekyll-style "all posts grouped by tag on one page" layout, use the grouped templates:

+++
title = "Posts by Category"
template = "categories_grouped.html"
+++

Every post, grouped by category.

tags_grouped.html is the tag equivalent. They complement (not replace) the per-tag and per-category index pages generated automatically under /tags/<name>/ and /categories/<name>/.

Output

Building generates:

dist/
├── index.html               # Home page
├── style.css                 # Theme stylesheet (built-in theme)
├── 404.html                  # Not found page
├── about/index.html          # Static pages
├── posts/
│   └── hello/index.html      # Blog posts
├── tags/
│   ├── index.html            # Tags listing
│   └── rust/index.html       # Per-tag post listing
├── categories/
│   ├── index.html            # Categories listing
│   └── tutorials/index.html  # Per-category post listing
├── page/
│   └── 2/index.html          # Pagination pages
├── search/
│   └── index.html            # Search page
├── projects/
│   ├── index.html            # Collection index
│   ├── my-project/index.html # Collection items
│   └── archived/
│       └── old-project/index.html  # Nested collection items
├── rss.xml                   # RSS feed
├── atom.xml                  # Atom feed
├── sitemap.xml               # Sitemap
└── search-index.json         # Client-side search index

As a Library

Use bamboo-ssg as a library in your own tools:

[dependencies]
bamboo-ssg = "0.5.3"

use bamboo_ssg::{SiteBuilder, ThemeEngine};

let mut builder = SiteBuilder::new("./my-site")
    .base_url("https://example.com")
    .include_drafts(false);

let site = builder.build()?;

let theme = ThemeEngine::new("default")?;
theme.render_site(&site, "./dist")?;

License

Dual-licensed under MIT (LICENSE-MIT) or Apache 2.0 (LICENSE-APACHE).