reference projects — Birkly Docs

Six copy-paste starter sites ship with the Birkly CMS. Each demonstrates real templating patterns with live birkly-client.js only — no hydrate, snapshots, or custom fetch() in site JavaScript.

In short: Six starter sites (blog, portfolio, yoga, coffee, social, influencer) ship under Birkly reference-projects/. Install with scripts/install-reference-project.sh <name>, then open /reference-projects/<name>/website/. All use live birkly-client.js only — list/detail/forms match the canonical syntax. Prefer these before inventing your own patterns. Step-by-step build: Worked site walkthrough.

Video (follow-along): coming — multi-step recording (install blog starter → list/detail)

Beginner

What are they?

Think of reference projects as starter kits: each one is a small website with sample content and HTML templates already wired to Birkly. You can browse them to see how loops, conditionals, commerce forms, and login pages work — then copy ideas into your own site.

The six projects

Project	Good for	Needs plugins?
blog	Homepage, post list, article pages	No
portfolio	Project gallery and case-study detail	No
yoga	Class schedule and event registration	Events
coffee	Product grid, variants, add to cart	Commerce
social	Login, feed, profile, comments, merch	User Management + Commerce
influencer	Blog + events + shop + social on one site	Events + Commerce + User Management

How to try one

Start the Birkly dev server from the Birkly folder (see Getting started).
Install a project (replace blog with any name from the table):

chmod +x ./scripts/install-reference-project.sh
./scripts/install-reference-project.sh blog

Open the site in your browser, for example:

http://localhost:8080/reference-projects/blog/website/index.html

Swap blog for portfolio, yoga, coffee, social, or influencer in both the install command and the URL.

For yoga, coffee, social, or influencer, install and activate the listed plugins first (Admin → Plugins), then run the install script.

What you will not see

Reference projects intentionally do not use advanced production tricks (pre-baked HTML, hydrate scripts, or snapshot files). That keeps them easy to learn and copy. If you need those techniques later, see Production optimization.

Advanced Users

Source layout (Birkly repo)

reference-projects/
├── blog/
│   ├── manifest.json       # optional plugins list
│   ├── collections/        # copied → content/collections/ on install
│   └── website/            # static HTML served from CMS root
├── portfolio/
├── yoga/
├── coffee/
├── social/
└── influencer/

Install script

scripts/install-reference-project.sh <project-name>:

Copies reference-projects/<name>/collections/* → content/collections/
Prints required plugins from manifest.json when present
Website files stay in place under reference-projects/<name>/website/

Canonical URLs (local dev)

Project	Index URL
blog	`/reference-projects/blog/website/index.html`
portfolio	`/reference-projects/portfolio/website/index.html`
yoga	`/reference-projects/yoga/website/index.html`
coffee	`/reference-projects/coffee/website/index.html`
social	`/reference-projects/social/website/index.html`
influencer	`/reference-projects/influencer/website/index.html`

Client contract (all projects)

<script src="/birkly-client.js" data-cms-url="http://localhost:8080"></script>

Templating + data-birkly-* attributes for forms, auth, commerce
Slug pages: meta[name=birkly-page], meta[name=birkly-collection], optional meta[name=birkly-slug]
No birkly-hydrate.js, no <meta name="birkly-baked">, no snapshot globals, no custom fetch() in site JS

Combining projects

Install merges collections by slug into content/collections/. Re-installing overwrites same-slug collections (blog, events, etc.). Use separate CMS instances or rename slugs when combining manually.

Upstream catalog

User-story IDs (V-TPL-01 … V-TPL-06) and per-page acceptance criteria live in the Birkly repo: docs/reference-projects/user-stories.md and each project's VIDEO.md.

Marketing site (Birkly-Website)

The public marketing site is not one of the six reference-projects/ starters, but it follows the same Light DOM rule for chrome:

Header/footer markup lives in each HTML page inside <birkly-header> / <birkly-footer>.
Site JS (js/components.js) is enhance-only — it never assigns innerHTML on those hosts (that would wipe CMS templates).
Active nav uses platform birkly-components.js → BirklyComponents.setActiveNav.

Prefer <birkly-region collection="site_elements" entry="header"> when chrome is CMS-authored; use the enhance-only pattern when chrome is intentionally static (logo + hardcoded nav), as on Birkly-Website.