Configuration ⚙️

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

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, .mdx, or .tsx files. Frontmatter optional for Markdown/MDX:

---
title: Page Title
description: Description for SEO
sidebar: true
toc: true
---

# Heading

Content here.

#Custom pages (.tsx)

For fully custom layouts (landings, marketing pages), add a SolidJS page:

// docs/index.tsx
export const sidebar = false
export const toc = false
export const title = "Home"
export const description = "Welcome"

export default function Page() {
  return (
    <main class="mx-auto max-w-3xl px-6 py-16">
      <h1 class="text-4xl font-bold">Welcome</h1>
      <p class="mt-4 text-muted-foreground">Custom landing page.</p>
    </main>
  )
}

Named exports mirror MDX frontmatter. sideNav is accepted as an alias for sidebar.

Every route must have exactly one page file. Gittydocs reports an error when multiple files resolve to the same route—for example, index.tsx and index.mdx both resolve to /. Move the previous home content to an explicit route only when that is your intended information architecture; Gittydocs does not automatically create an /introduction route.

Custom pages can keep private components beside the docs in an underscore-prefixed folder. Gittydocs copies these files for bundling but excludes them from routes, navigation, search, source maps, and llms.txt:

docs/
  index.tsx
  _components/
    Hero.tsx
    icons.tsx
    landing.css

// docs/index.tsx
import { Hero } from "./_components/Hero"
import "./_components/landing.css"

Private component folders support .ts, .tsx, .js, .jsx, and .css files.

Files sorted by:

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

Routing follows the folder structure:

index.mdx            # /
index.tsx            # / (custom page; cannot coexist with 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.