Gemara Website

This repo builds gemara.openssf.org.

It is a Jekyll site. Most pages are plain Markdown that you can edit directly.

Gemara itself lives somewhere else. The CUE schemas and the model spec are in gemaraproj/gemara. This repo is only the website.

---

What you probably came here to do

I want to...	Go to
Fix a typo or reword a page	Edit a page
See my change in a browser	Run the site locally
Add a new page	Add a new page
Change a schema reference page	Generated pages
Understand the build	How the build works

---

Edit a page

Site content sits at the root of the repo, sorted by folder:

Folder	What's in it
index.md	The home page
model/	The Gemara model, written as chapters
tutorials/	Hands-on walkthroughs
sdk/	SDK docs
adrs/	Architecture Decision Records
community/	Meetings, Slack, maintainers
schema/	Schema reference (mostly generated — see below)

Every page starts with a small block of front matter, like this:

---
layout: page
title: My Page Title
---

Your content starts here.

Keep the front matter. Edit everything below it.

---

Run the site locally

You need Ruby 3.2 or newer and Go 1.25 or newer.

Go is needed because the schema pages are generated by a tool in the spec repo.

make deps     # install Ruby dependencies (run once)
make serve    # build and serve the site

Then open http://localhost:4000.

The page reloads on its own when you save a file.

Before you commit

make cleanup

This deletes generated files so they don't end up in your commit. Generated files are also in .gitignore, so this is a safety net rather than a hard requirement.

---

Add a new page

1. Create a .md file in the right folder.
2. Give it front matter (layout: page and a title:).
3. Add it to the navigation in _data/sidebar.yml or _data/navigation.yml.
4. Run make serve and check it looks right.

---

Generated pages: do not edit these

Some files are written by a build script. If you edit them, your changes get wiped.

Path	Comes from
schema/*.md (except schema/index.md)	The CUE schemas in the spec repo
model/02-definitions.md	lexicon.yaml + model/02-definitions.md.template
generated/	Intermediate build output
_site/	The final built site

To change a schema page, change the CUE schema in gemaraproj/gemara.

To change a definition, edit lexicon.yaml in this repo.

A note on term links

The build automatically turns defined terms into links across all pages. That means make serve may leave link markup in your working copy.

make cleanup removes it again. Run cleanup before you commit.

---

How the build works

gemaraproj/gemara  ──►  CUE schemas + the gemara-docs CLI
        │
        │  make gendocs  (clones the spec into .gemara-spec/)
        ▼
   generated/  ──►  schema/*.md  and  model/02-definitions.md
        │
        │  jekyll build
        ▼
     _site/  ──►  GitHub Pages  ──►  gemara.openssf.org

By default the build clones the spec repo into .gemara-spec/.

To build against a local checkout of the spec instead:

make serve GEMARA_DIR=../gemara

Make targets

Command	What it does
make deps	Install Ruby dependencies
make serve	Generate docs, then serve with live reload
make build	Generate docs, then build into _site/
make gendocs	Generate schema pages and definitions only
make test-links	Check the built site for broken links
make cleanup	Delete generated files and term links
make all	gendocs + test-links + cleanup

---

Deployment

Deployment is automatic. You don't need to run anything.

.github/workflows/deploy.yml handles it:

• Pull request → builds the site and checks links. No deploy.
• Push to main → builds and deploys to GitHub Pages.
• New spec release → the spec repo pings this repo, which rebuilds against the new release.
• Manual run → you can trigger a build against any spec ref from the Actions tab.

Normal builds use the latest published spec release, not the spec's main branch.

---

Contributing

Pull requests are welcome.

• Sign your commits: git commit -s (DCO is required)
• Use Conventional Commits for PR titles, for example docs: fix typo on the model page
• Run make cleanup before committing

Come talk to us first if you're planning something large:

• Slack: #gemara on OpenSSF Slack
• Meetings: every other Thursday — see the OpenSSF calendar

Maintainers are listed in _data/maintainers.yml.

---

Troubleshooting

make serve fails saying Jekyll isn't available Run make deps first.

Schema pages are empty or missing The spec checkout may be stale. Delete it and try again: rm -rf .gemara-spec && make gendocs

Weird link markup all over my diff That's the term linker. Run make cleanup.

Port 4000 is already in use Another Jekyll server is still running. Stop it, or serve on a different port: bundle exec jekyll serve --port 4001

---

Copyright © Gemara contributors, a Series of LF Projects, LLC.