WingTip Roadmap

Objective

Make WingTip the most reliable way to move a documentation project from a hosted platform to portable static output: migrate an existing repository, preserve its information architecture and URLs, and prove the result with automated search, performance, and integrity audits.

WingTip will not try to reproduce every hosted collaboration feature. It will compete on ownership, migration quality, technical discovery, build transparency, portability, and zero mandatory platform cost.

Current position

Status reflects the repository as of July 18, 2026. Competitor capabilities change; any public comparison must be generated from a reproducible fixture rather than unsupported marketing claims.

Delivery plan

Phase 1 — Migration quality (P0)

Content and navigation model

• ✅ Recursively discover .md content (.mdx compatibility still pending)
• ✅ Preserve nested source paths in generated URLs (docs/guides/intro.md → guides/intro.html)
• ✅ Ordered navigation groups: _category.json (name, order) per directory, order/nav_order frontmatter per page
• ✅ Render grouped/collapsible navigation from the directory tree
• ✅ Detect duplicate output paths (collisions are warned and skipped)
• ✅ GFM fidelity: task lists, GitHub alerts, strikethrough, bare-URL autolinks (July 18, 2026)
• ✅ Visible breadcrumb navigation in the page body, matching the JSON-LD trail (July 18, 2026)
• ✅ Section hub pages: _category.json "index": true generates a landing page per directory, with an Overview nav link and linked breadcrumbs (July 18, 2026)
• ✅ Pinned left sidebar on wide desktop (≥1200px); hamburger/slideout below (July 18, 2026)
• Introduce tabs, products, versions, and languages in the navigation model — design decided July 18, 2026: locale/version become first-class dimensions (one nav tree definition, per-dimension instances, scoped search, hreflang/canonical mechanics per dimension) and this moves AHEAD of generic nav sharding, because dimensions both shrink the scaling problem and unblock migration fidelity for platform configs that use them
• Detect orphaned navigation entries

Hosted-platform importer

wingtip migrate ./existing-docs --output ./wingtip-docs

Shipped (read-only — the source project is never modified):

• ✅ Read current and legacy platform configuration formats (docs.json, mint.json)
• ✅ Import project name, description, brand colors, and favicon
• ✅ Convert navigation groups to directory _category.json files and per-page order frontmatter
• ✅ Preserve page paths in generated URLs; report every preserved URL
• ✅ Rewrite platform-style absolute internal links to portable relative links
• ✅ Inventory MDX components per page; strip module import/export lines and MDX comments
• ✅ Approximate common MDX components (callouts → blockquotes, titled sections → labels, Card → link, src-bearing components → images) with JSX dedenting
• ✅ Rewrite links in raw href/src attributes with page-relative → site-root → case-insensitive resolution
• ✅ Stub dynamic link expressions and report suspected broken links in the source
• ✅ Carry platform redirects into config.json; every build emits static redirect pages plus a Netlify/Cloudflare _redirects file with wildcard→splat translation (July 18, 2026)
• ✅ Never silently discard unsupported configuration or content — everything unhandled is listed in the report
• ✅ Validated against real public hosted-docs repositories (46 → 5,387 pages)

Still pending:

• Resolve local JSON $ref configuration
• Convert tabs, products, versions, and languages beyond flat group mapping
• Preserve OpenAPI references for Phase 2 endpoint rendering
• Unique-basename fallback for bare links that the source platform resolved via navigation context (found at the 5,000-page tail)
• Treat snippets/ include-partials as includes (inline where referenced, or skip and report) instead of standalone pages
• Copy non-image media (video, PDF, downloads) referenced by pages into the build output — currently only rendered images and static/ ship

Migration report

• ✅ Every migration emits migration-report.md in the new project: an executive summary (format detected, pages converted, URLs preserved, groups mapped, manual follow-up count) followed by ✓ converted items and ⚠ manual work (components per page, unmapped groups, orphan pages, redirects, configuration not carried) and next steps

Still pending:

• Machine-readable JSON report alongside the Markdown
• Broken links and missing assets detection at migrate time (the post-build audit covers this after wingtip runs)
• File/line locations for component occurrences

Migration documentation and evidence

• ✅ Open-source hosted-platform migration guide (July 17, 2026)
• ✅ Migration intake through a dedicated GitHub issue template (July 17, 2026)
• Create a sanitized real-world hosted-docs fixture for regression testing
• Record a repository-to-deployed-site migration demo
• Document output ownership, supported hosts, and unsupported constructs plainly

Exit criteria: Representative hosted-platform repositories build without lost pages, URLs, metadata, or unreported incompatibilities, and a prospective user can verify that from the published guide, fixture, and demo.

Phase 2 — Documentation parity (P1)

Prioritize capabilities that block real migrations:

• OpenAPI 3.x ingestion and endpoint-page generation
• API operation navigation, parameter/schema tables, examples, and code samples
• Optional static-first API playground enhancement
• AsyncAPI inventory and design
• Tags: tags: frontmatter → generated per-tag index pages and a tags hub; related-pages block per page (tag overlap + directory siblings, computed at build time)
• Search weighting/boost frontmatter and section-level result anchors
• Visible version, product, and language switchers
• Redirect validation and redirect-chain detection
• Mermaid diagrams — approach decided July 18, 2026: vendor mermaid.min.js locally (no CDN), lazy-loaded only on pages containing diagrams; build-time SVG rejected (would add a Node dependency to a Python tool)
• Common hosted-platform MDX compatibility components: cards, columns, tabs, accordions, steps, callouts, frames, and code groups
• Reusable snippets/includes and content variables
• Navigation banners, badges, deprecation labels, and hidden-page controls
• Formal, versioned plugin API and template/theme extension points

Exit criteria: A typical public SaaS documentation repository does not need to remain on a hosted documentation platform solely for navigation, common MDX presentation, or OpenAPI reference pages.

Phase 3 — Search-engineering leadership (P1)

Turn the existing auditor into a differentiated discovery system:

• Validate titles, descriptions, canonicals, robots directives, OG/Twitter metadata, and JSON-LD
• ✅ Zero-config social metadata decided and shipped: og:url/og:image/twitter:image are emitted only when absolute, per the OpenGraph spec; canonicals deliberately stay relative-self-resolving (July 18, 2026)
• Detect canonical conflicts, duplicate metadata, orphan pages, broken fragments, redirect chains, and accidental noindex
• Validate hreflang reciprocity, language codes, canonicals, and x-default clusters
• Audit internal-link depth and surface pages with weak contextual connectivity
• Add configurable HTML, CSS, JavaScript, image, request-count, and font performance budgets
• Shard or lazy-load sidebar navigation for very large sites: per-page full navigation makes total output size quadratic in page count (measured: a 5,387-page site emits a ~5,300-entry sidebar on every page, ~3.9GB total). Design decided July 18, 2026 — “context window” nav: each page inlines ancestors + siblings + children server-side (crawlable, bounded), full tree in a shared nav.json hydrating the slideout on demand; hub pages keep every page within ~3 clicks. Search-index and llms-full sharding follow the same per-section pattern. Sequenced after the dimension model (see Phase 1)
• Audit at scale: parallelize the post-build audit per file (it is embarrassingly parallel) and add incremental auditing keyed on content hash so CI re-audits only changed pages. At the 5,387-page tail the full audit takes tens of minutes — a gate that slow gets skipped, and a skipped gate protects nothing. (Typical 50–300 page sites audit in seconds.)
• ✅ Same-origin absolute URLs resolve against the local build (base detected from the index canonical), closing the blind spot that hid a dead 404 Markdown alternate on the demo site (July 18, 2026)
• Emit machine-readable audit output for CI annotations
• Generate a crawl graph and diff it between builds
• Add optional answer-first/content-structure linting without making ranking promises
• Generate skill.md, multiple skill manifests, integrity hashes, and well-known discovery endpoints from project-owned source files
• Add schema types appropriate to API references, software applications, organizations, and FAQs only when content qualifies

Exit criteria: WingTip catches technical discovery regressions before deployment and produces evidence that can be inspected in CI.

Phase 4 — Reproducible competitive benchmark (P1)

Build the same public fixture with WingTip and representative hosted and open-source documentation generators. Record:

• Build inputs, product versions, commands, and generated artifacts
• HTML availability without client-side JavaScript
• Page weight, requests, external origins, and JavaScript execution
• Lighthouse and Core Web Vitals lab results under identical conditions
• Canonical, robots, sitemap, hreflang, social metadata, structured data, and AI-readable artifacts
• Broken-link, accessibility, and schema validation results
• Hosting portability and platform-dependent behavior

Publish raw outputs and rerunnable automation. Do not claim leadership where the fixture does not prove it.

Exit criteria: Competitive claims in the README and launch material are generated from public evidence.

Phase 5 — Workflow and ecosystem (P2)

• wingtip new, wingtip check, and wingtip migrate command groups
• Browser build-error overlay and improved incremental rebuilds
• Preview-deployment recipes for GitHub, Netlify, Cloudflare Pages, and Vercel
• PR annotations for audit regressions and visual changes
• Theme packages and template overrides
• WCAG 2.2 AA audit and regression checks (✅ automated axe-core gate over every generated page in both color schemes, in CI with a negative test, July 17, 2026; expert manual audit still open)
• Contributor guide, extension examples, and stable fixtures
• Dependency, package-integrity, and generated-CSP checks

Phase 6 — Optional hosted capabilities (P3)

Keep the open-source generator complete on its own. Hosted or partner services may later provide:

• Managed builds and previews
• Password-protected or authenticated documentation
• Team editing and approval workflows
• Search/feedback analytics
• Edge redirects, headers, and cache controls
• Enterprise support and migration services

These services must not make existing static generation, SEO metadata, auditing, or output ownership dependent on a WingTip account.

Success metrics

• Migration completion rate and median manual fixes per repository
• Percentage of source pages, URLs, redirects, and metadata preserved
• Unsupported MDX constructs per migrated repository
• Zero unreported data loss
• Audit findings caught before production
• Generated page weight and external-origin count
• Build time across small, medium, and large fixtures
• Number of independent deployments that do not use WingTip-managed infrastructure
• Search impressions, indexed pages, and AI referrals measured by adopters who opt to share results

Explicit non-goals

• Guaranteed rankings, rich results, or AI citations
• A proprietary content repository
• Mandatory cloud hosting
• Recreating every collaborative editor feature before migration quality is excellent
• Generating large volumes of low-quality programmatic content

Edit this page on GitHub