girk-sdk

Girk

Markdown-first static sites without the sprawl.

Girk turns a plain folder of Markdown, media, and a small JSON config into a static site you can deploy anywhere.

Why Girk

Most static site workflows get harder as soon as the content grows. Girk goes the other direction: the file tree stays the project model, Markdown stays the source of truth, and the generated site stays easy to host.

Use it for:

• documentation sites
• product and marketing sites
• handbooks and knowledge bases
• blogs, journals, and archive-driven sections
• multilingual content trees

Start In One Command

npx girky

Run that in a folder that contains Markdown files. Girk scans the project, derives routes from the structure, applies frontmatter and config, and writes the generated site to public/.

Supported Node versions: 20.19+, 22.12+, and 24 through 25.

Minimal Project

my-site/
  README.md
  features/
    README.md
    archives.md
  media/
    logo.svg

That becomes:

• /
• /features/
• /features/archives/

How It Works

1. create a content tree with Markdown files
2. add frontmatter or config only where needed
3. run the generator
4. deploy the generated public/ folder

Core Features

• the file tree is the route model
• Markdown stays the source of truth
• frontmatter handles page behavior without extra tooling
• girk.config.json keeps shared project defaults in one place
• build-time data sources can repeat content or generate detail pages from one template
• the output is static HTML, CSS, and assets
• archive layouts for grouped content
• multilingual support
• styling hooks, custom scripts, web components, and Vue mounts

Quick Config Example

{
  "project": {
    "title": "My Site",
    "description": "A practical static site",
    "style": "/assets/site.css",
    "scriptModule": "/assets/components.js"
  }
}

Useful project hooks:

• projectStyle adds a stylesheet after the generated one
• projectStyleOverrule replaces the generated stylesheet
• projectScript adds classic scripts before </body>
• projectScriptModule adds type="module" scripts before </body>

Learn More

• Docs: https://girk.dev
• Features: https://girk.dev/features/
• How to Use: https://girk.dev/how-to/
• Examples: https://girk.dev/examples/
• Release Notes: https://girk.dev/release-notes/

Example sites:

• https://example-basic.girk.dev/
• https://example-multilang.girk.dev/
• https://example-config.girk.dev/
• https://example-blog.girk.dev/
• https://example-recipes.girk.dev/

Good Fit If

• you want a content-first site without a CMS
• you want route structure to come from folders instead of config files
• you want a small setup that AI can reason about correctly
• you want to ship documentation or marketing content fast

Repository

This repository contains:

• packages/girk: the publishable girky package and the girk CLI
• apps/docs: the docs site generated by Girk itself
• apps/example-basic: a single-language example project with broad feature coverage
• apps/example-multilang: a multilingual example project focused on translated routes and language switching
• apps/example-config: a config-driven example with girk.config.json
• apps/example-blog: a focused blog archive example
• apps/example-recipes: a checklist-driven recipes example

Common commands from the repo root:

• npm run build
• npm run test
• npm run test:examples
• npm run test:e2e
• npm run serve:docs

Releases

girky is published from GitHub Actions with semantic-release.

• Workflow: .github/workflows/publish.yml
• Branch: main
• Published package: packages/girk (girky on npm)
• Versioning: derived automatically from conventional commits

Dry-run the release logic locally with:

npm run release:dry-run

Deployment

The docs and example sites are deployed through a single Worker with static assets.

Route mapping:

• girk.dev/* -> docs
• www.girk.dev/* -> docs
• example-basic.girk.dev/* -> example basic
• example-multilang.girk.dev/* -> example multilang
• example-config.girk.dev/* -> example config
• example-blog.girk.dev/* -> example blog
• example-recipes.girk.dev/* -> example recipes

Relevant commands:

• npm run cf:build:sites
• npm run deploy:sites