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.

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

Install

Run it directly:

npx girky

Or install it globally:

npm install --global girky

Then run:

girk

What It Does

Girk keeps the content model simple:

• the file tree becomes 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 fan one template out into many pages
• optional build-time search stays fully static
• the output is static HTML, CSS, and assets

Use it for:

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

Minimal Project

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

That becomes:

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

Quick Start

1. create a folder with Markdown files
2. run npx girky
3. open the generated public/ folder
4. add frontmatter or config only where needed

Config Hooks

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>
• projectSearch enables the built-in static search index and client

Example:

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

Static Search

Turn search on once:

{
  "projectSearch": true
}

Girk then generates static search assets in public/assets/search/ and injects the built-in client into the generated pages.

You can also enable it more narrowly in frontmatter:

---
search: true
---

That enables the header search UI on one page.

---
archive: sections
archiveSearch: true
---

That enables the same UI on an archive landing page and its archive children.

The default UI is a small search icon button in the header. Clicking it opens a centered search overlay with a focused input and live result links.

Optional tuning:

• projectSearchSharding: auto, language, or section
• projectSearchBodyLimit: cap the body text that is indexed per page
• searchScope: optional default scope override, project by default

Use searchExclude: true on a page to keep it out of the generated index.

If that page is a folder landing page such as README.md or index.md, Girk excludes that whole section from search.

Customisation

Girk supports:

• custom CSS layered on top of the default theme
• full stylesheet replacement
• custom JavaScript
• custom web components
• Vue-powered mounts from browser-ready scripts
• JSON-driven build-time content from local files or remote endpoints

Build-Time Data Sources

Use page frontmatter when one Markdown file should be driven by structured JSON:

---
dataSource: data/projects.json
dataItems: items
title: Projects
---

{{#each result}}
## [{{result.title}}](/projects/{{result.slug}}/)
{{result.summary}}
{{/each}}

Use dataSlug when one template file should generate many real pages:

---
dataSource: data/projects.json
dataItems: items
dataSlug: slug
title: {{result.title}}
---

# {{result.title}}

dataSource accepts remote JSON URLs and local JSON files resolved from the project root.

Remote endpoint example:

---
dataSource: https://jsonplaceholder.typicode.com/posts
title: Posts
---

{{#each result}}
## {{result.title}}
{{result.body}}
{{/each}}

Remote JSON is fetched at build time. If the endpoint is unavailable, the build fails.

Girk does not compile Vue for you. You ship browser-ready assets and reference them from project settings.

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/

Repository

Source code and docs live in the monorepo:

• package source: packages/girk
• docs site: apps/docs
• examples: apps