WingTip

Open-source, SEO-first documentation sites from Markdown.

Live demo · Migration guide · Source · Roadmap

WingTip turns a repository README.md and docs/ directory into fast, portable static documentation. It generates crawlable HTML, search and discovery metadata, structured data, machine-readable Markdown artifacts, and an offline-capable site without requiring a hosted documentation platform.

Start with zero configuration, customize when needed, and deploy the generated files anywhere.

Why WingTip

• Own the output: Build ordinary HTML, CSS, JavaScript, feeds, and metadata that can be hosted on any static file server.
• Built for discovery: Generate canonical URLs, robots directives, sitemap metadata, Open Graph and Twitter cards, TechArticle and breadcrumb JSON-LD, RSS, and hreflang alternates.
• Built for AI retrieval: Publish llms.txt, full concatenated documentation, and a Markdown alternate beside every generated page.
• No mandatory CDN runtime: Core styles, scripts, icons, KaTeX, and fonts are vendored into the Python package and copied into the build. External analytics remain opt-in.
• Your branding only: No "powered by" badge, injected links, or generator watermarks — the generated site carries your identity, not WingTip's.
• Zero infrastructure: Search, navigation, PWA support, and offline fallback work from static hosting.

Moving from hosted documentation?

Use the migration guide to assess what WingTip supports today, preserve URLs and metadata, validate generated output, and plan a safe cutover. Public repositories and sanitized reproductions can request a structured migration review.

Features

Search, SEO, and machine-readable output

• Per-page title, description, keywords, canonical URL, robots/noindex, language, Open Graph, and Twitter overrides
• Automatic description fallback from the first paragraph
• TechArticle and BreadcrumbList JSON-LD
• sitemap.xml, robots.txt, RSS, llms.txt, and full concatenated documentation
• Raw Markdown alternates emitted as .html.md
• Published/updated dates with Git-based modified-date fallback
• Per-page categories and versions, plus generated categories.json and versions.json
• Per-page language and translation mappings with hreflang and x-default
• Local client-side full-text search with keyboard navigation (details)

Documentation experience

• README.md becomes index.html; docs/ is discovered recursively with nested paths preserved in URLs (docs/guides/intro.md → guides/intro.html)
• Automatic sidebar with collapsible directory groups (_category.json for names and ordering, order frontmatter for pages), table of contents, and previous/next navigation
• GitHub “Edit this page” links
• Responsive layout with light/dark mode and screen-reader/keyboard support
• Pygments syntax highlighting and copy-to-clipboard controls
• Tables, footnotes, definition lists, attributes, admonitions, and Markdown inside HTML
• KaTeX math rendering (examples)
• Configurable external-link handling and correct .md link rewriting, including fragments and queries
• Custom Markdown-based 404.html

Performance, security, and extensibility

• Local image copying, lazy loading, intrinsic dimensions, and responsive srcset generation
• Locally vendored core frontend assets
• PWA manifest, service worker, precache, and offline fallback
• PWA icons generated only from a project-supplied favicon.png
• Optional generated or custom Content Security Policy
• Plausible, Umami, Fathom, Google Analytics, custom analytics, and global/per-page <head> snippets
• Plugin hooks before/after builds and conversions, plus plugin-provided Python-Markdown extensions
• Theme variables through theme.json and static CSS overrides (theming guide)
• Live development server with auto-reload and scroll restoration
• Post-build auditor for missing local files, unexpected CDN references, required artifacts, and branding leaks

Installation

Python 3.9 or newer is required.

pip install wingtip

Install the optional live server:

pip install "wingtip[serve]"

For local development from a clone:

pip install -e ".[dev]"

Quickstart

Create a project containing README.md and, optionally, a docs/ directory:

your-project/
├── README.md
├── docs/
│   ├── guide.md
│   └── api.md
├── config.json       # optional
├── theme.json        # optional
└── favicon.png       # optional; enables favicon and PWA icon generation

Run WingTip from the project directory:

wingtip

The default output is docs/site. To build another source directory into a chosen destination:

wingtip --source ./your-project --output ./build

Start the live development server after building:

wingtip --serve

Use wingtip --help for all CLI options.

Configuration

Configuration is optional. Without config.json, WingTip derives the project name from the README.md heading or source-directory name and uses relative URLs for local portability.

Add config.json when you want production URLs, repository links, analytics, security policy, or social-card customization:

{
  "base_url": "https://docs.example.com",
  "project_name": "Acme API",
  "version": "1.0.0",
  "description": "Integration documentation for the Acme API.",
  "author": "Acme",
  "repo_url": "https://github.com/acme/api-docs",
  "og_image": "social-card.png",
  "twitter_handle": "@acme",
  "github": {
    "repo": "acme/api-docs",
    "branch": "main"
  },
  "analytics": {
    "provider": "plausible",
    "domain": "docs.example.com"
  },
  "csp": true,
  "social_card": {
    "title": "Acme API",
    "tagline": "Build with Acme.",
    "theme": "light",
    "font": "Poppins"
  }
}

Place a local favicon.png in the project root to emit favicon/nav-logo markup and generate 192×192 and 512×512 PWA icons. If it is absent, WingTip emits none of those branded assets.

Per-page frontmatter

Use YAML frontmatter to control individual pages:

---
title: Authentication API
description: Authenticate server-side requests to the Acme API.
keywords:
  - API authentication
  - OAuth
canonical: https://docs.example.com/authentication
noindex: false
author: Acme Developer Relations
date: 2026-07-16
lastmod: 2026-07-17
category: API reference
version: v2
lang: en
translations:
  es: https://docs.example.com/es/authentication
og_title: Acme API authentication
twitter_description: Implement Acme API authentication.
---

Noindexed pages are excluded from the sitemap, search index, category/version indexes, and structured data.

Plugins and custom Markdown

Place Python modules in plugins/. WingTip can auto-load every module or load only names listed in the plugins array in config.json.

Plugins can expose:

• before_build(config, output_dir)
• before_convert(frontmatter, markdown, input_path, output_path)
• after_convert(html, frontmatter, input_path, output_path)
• after_build(config, output_dir)
• markdown_extensions, as a list or callable returning Python-Markdown extensions

Hook failures are reported as warnings so one extension does not silently stop the entire build.

Build auditing

The repository includes a post-build auditor used by CI:

python audit_site.py --output docs/site --source .

It exits non-zero when it finds:

• Missing local files referenced by generated HTML
• Known CDN origins for dependencies that WingTip vendors locally
• Missing required search, SEO, feed, or PWA artifacts
• Missing PWA icons when a project favicon was supplied
• Output assets byte-identical to packaged branding assets
• WingTip branding in a project whose configured name is not WingTip

CI also runs a negative fixture that deliberately injects a broken asset reference and verifies that the auditor fails.

GitHub Pages deployment

The included GitHub Actions workflow builds and deploys on pushes to main. For another repository, the essential build steps are:

- uses: actions/setup-python@v5
  with:
    python-version: "3.12"
- run: pip install wingtip
- run: wingtip
- uses: actions/upload-pages-artifact@v3
  with:
    path: docs/site

Set base_url to the final Pages URL so canonical, sitemap, feed, social, and alternate URLs are absolute in production.

Social cards

WingTip generates social-card.png during a build. Force regeneration after changing card settings:

wingtip --regen-card

The social_card object supports title, tagline, light/dark style, font, and an optional logo. Per-page og_image and twitter_image frontmatter can override the site image.

Custom 404 page

Create 404.md in the project root. WingTip converts it to 404.html with the same Markdown processing and site template as other pages:

---
permalink: /404.html
noindex: true
---

# Page not found

The requested documentation page does not exist.

Generated output

A normal build includes:

docs/site/
├── index.html
├── guide.html
├── guide.html.md
├── search_index.json
├── sitemap.xml
├── robots.txt
├── feed.xml
├── llms.txt
├── llms-full.txt
├── manifest.json
├── sw.js
├── offline.html
├── social-card.png
├── syntax.css
└── static/

categories.json and versions.json are emitted when pages declare those values. favicon.png, icon-192.png, and icon-512.png are emitted only when the project supplies a favicon.

Current limitations and roadmap

Mermaid diagrams, broad MDX compatibility, an automated hosted-platform importer, and a theme marketplace are not yet built.

See the roadmap and feature comparison for planned work.

License

MIT. Use freely. Modify ruthlessly.