Metadata-Version: 2.4
Name: wingtip
Version: 0.6.3
Summary: A static site generator for documentation that is built to be indexed and cited.
Project-URL: Homepage, https://semanticentity.github.io/WingTip-Static-Site-Generator
Project-URL: Source, https://github.com/semanticentity/WingTip-Static-Site-Generator
Project-URL: Issues, https://github.com/semanticentity/WingTip-Static-Site-Generator/issues
Author: SemanticEntity
License: MIT
Keywords: aeo,documentation,llms-txt,markdown,seo,static-site-generator
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: markdown>=3.5
Requires-Dist: pillow>=10.0
Requires-Dist: pygments>=2.17
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: livereload>=2.6; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: serve
Requires-Dist: livereload>=2.6; extra == 'serve'
Description-Content-Type: text/markdown

# WingTip

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

![WingTip social card](https://raw.githubusercontent.com/semanticentity/WingTip-Static-Site-Generator/main/social-card.png)

[Live demo](https://semanticentity.github.io/WingTip-Static-Site-Generator) · [Migration guide](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/migration.md) · [Source](https://github.com/semanticentity/WingTip-Static-Site-Generator) · [Roadmap](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/roadmap.md)

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](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/migration.md) 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](https://github.com/semanticentity/WingTip-Static-Site-Generator/issues/new?template=migration.yml).

## 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](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/search-features.md))

### 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](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/math-examples.md))
- 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](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/theming.md))
- 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.

```bash
pip install wingtip
```

Install the optional live server:

```bash
pip install "wingtip[serve]"
```

For local development from a clone:

```bash
pip install -e ".[dev]"
```

## Quickstart

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

```text
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:

```bash
wingtip
```

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

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

Start the live development server after building:

```bash
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:

```json
{
  "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:

```yaml
---
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:

```bash
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:

```yaml
- 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:

```bash
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:

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

# Page not found

The requested documentation page does not exist.
```

---

## Generated output

A normal build includes:

```text
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](https://github.com/semanticentity/WingTip-Static-Site-Generator/blob/main/docs/roadmap.md) for planned work.

---

## License

MIT. Use freely. Modify ruthlessly.
