gittydocsgittydocs

Configuration ⚙️

Everything you need to configure gittydocs from top-to-bottom (like a cheatsheet)

Create gittydocs.jsonc in your docs folder:

// docs/gittydocs.jsonc
{
  "$schema": "https://raw.githubusercontent.com/blankeos/gittydocs/main/gittydocs.schema.json",
  "site": {
    "name": "Site Name",
    "logo": "/logo.svg",
    "favicon": "/static/favicon.ico",
    "socialBanner": "/static/social-card.png",
    "repo": {
      "owner": "username",
      "name": "repo",
      "ref": "main",
      "docsPath": "docs",
    },
  },
  "nav": [
    {
      "label": "Section",
      "items": [
        { "label": "Page", "path": "/" },
        { "label": "Subpage", "path": "/subpage" },
      ],
    },
  ],
  "links": {
    "github": "https://github.com/user/repo",
    "issues": "https://github.com/user/repo/issues",
  },
}

$schema enables autocomplete + validation in editors. For a pinned version, swap main for a tag.

Options

FieldTypeDescription
site.namestringSite title
site.descriptionstringShort site description used in /llms.txt
site.logostringLogo image URL or public path
site.faviconstringFavicon URL or public path
site.socialBannerstringSocial preview image (Open Graph/Twitter) URL or path
site.repo.ownerstringGitHub username or org
site.repo.namestringRepository name
site.repo.refstringBranch or tag (default: main)
site.repo.docsPathstringPath to docs folder (default: docs)
navarrayCustom navigation sections
links.githubstringURL to repository or org
links.issuesstringURL to issues page
links.discordstringURL to Discord server
theme.presetstringPreset theme name (see /theming)
theme.cssFilestringPath to a CSS file in your docs folder (default: theme.css)
llms.enabledbooleanGenerate /llms.txt at build time (default: true)
llms.pathstringFolder for per-page LLM markdown (default: llms)

site.logo, site.favicon, and site.socialBanner can be full URLs or paths to files in public/. Relative paths are resolved with the base URL.

Static Assets / Images

Place images and other static assets in docs/[static]/ or docs/[images]/. Both folders are special: their contents are copied to public/static/ and served from /static/....

docs/
  [images]/
    hero.png
![Hero](/static/hero.png)

For more theming details and presets, see /theming.

Source

Set GITTYDOCS_SOURCE environment variable to point to your docs:

GitHub URL (auto-parsed):

GITTYDOCS_SOURCE=https://github.com/owner/repo/tree/main/docs

Local path (absolute):

GITTYDOCS_SOURCE=/absolute/path/to/docs

Writing Content

Use .md or .mdx files. Frontmatter optional:

---
title: Page Title
description: Description for SEO
---

# Heading

Content here.

Files sorted by:

  1. index.* first
  2. Numeric prefix (01-intro.md)
  3. Alphabetical

Routing follows the folder structure:

index.mdx            # /
subtopic/index.mdx   # /subtopic
subtopic/topic.mdx   # /subtopic/topic

Fully Customize

Gittydocs is essentially a template repackaged as a CLI, thinly wrapped around Velite, SolidJS, and Vike. For full control:

bunx gittydocs@latest new docs --ejected
cd docs
bun install

Edit velite.config.ts, components, styles. Deploy the same way.

When should I eject?

  • I need custom UI or layout changes beyond the config.
  • I need to change the content pipeline (custom MDX components or plugins).
  • I am okay maintaining a fork that can drift from upstream and get outdated.