DocsHub architecture: Wombat

Wombat is the current architectural generation of DocsHub. It is a statically generated documentation site for the ZFordDev ecosystem, built with Eleventy, Markdown, Nunjucks, Tailwind CSS, and browser-side JavaScript.

This page distinguishes the current implementation from active cleanup work and future plans. A planned capability is not available unless it appears under Implemented now.

Status at a glance

Implemented now

Static documentation build

Eleventy reads content from src/ and writes a static site to _site/. Markdown and Nunjucks pages use shared layouts and reusable header, sidebar, banner, footer, search, and homepage components. Tailwind CSS supplies the site styles and typography rules.

The production build is:

npm run build

This compiles the stylesheet and generates the site. DocsHub has no application server, database, account system, or server-side authoring interface in this repository.

Markdown rendering

DocsHub uses one configured Markdown-it renderer. The current extensions include:

• syntax highlighting;
• footnotes and task lists;
• heading anchors;
• marks, subscript, and superscript;
• external-link attributes; and
• note, warning, tip, and info callout containers.

Raw HTML is enabled because several pages and shared components include custom markup.

Document metadata

Markdown pages can declare fields such as project, module, category, title, description, tags, weight, and context_priority in front matter. The build currently uses this metadata primarily for page identity and search index records.

Metadata does not currently generate the homepage project list, project navigation, category pages, related-document lists, or version views. Those areas remain manually authored or unimplemented.

Local documentation search

The build creates /search-index.json from Markdown pages. Each record contains the page title, description, URL, project, module, category, tags, weight, context priority, and text extracted from the source document.

The browser downloads this index and performs search locally. Current matching supports:

• exact token matches;
• prefix matches;
• limited typo tolerance using Levenshtein distance;
• weighted title, tag, metadata, description, and body-content fields;
• small document-weight and URL-context boosts; and
• up to eight results per query.

Recent searches are stored in browser local storage. Breadcrumb text and context chips are derived from the current URL.

The context chips are informational, not filters. Related Docs is a placeholder, and the result list does not yet implement arrow-key selection.

Deployment

Pushing to main starts the GitHub Actions deployment workflow. It:

1. installs the locked npm dependencies;
2. runs the production build; and
3. replaces the generated contents of the host branch.

The repository documentation states that Cloudflare serves that configured branch. Deployment is therefore automated static publishing, not a general hosting product or user-configurable publishing service.

In progress

Current Wombat work is strengthening the existing static documentation system:

• removing broken or misleading navigation;
• separating current, planned, legacy, and archived material;
• resolving contradictory product instructions;
• improving metadata and page identity;
• making privacy and service boundaries concrete;
• tuning search relevance against real documentation; and
• expanding validation as new metadata and publishing rules are introduced.

These are maintenance and information-architecture improvements to the current site. They do not introduce accounts, collaborative editing, or managed hosting.

Planned within Wombat

The following capabilities fit the static Wombat architecture but are not implemented yet:

• metadata-generated project, category, and tag discovery pages;
• explicit version and compatibility metadata;
• version-aware navigation and filtering;
• metadata-driven related-document suggestions;
• removable project and module search filters;
• full keyboard navigation for search results;
• stronger archive exclusion from current search and navigation;
• documented self-hosting and deployment options beyond the existing project workflow; and
• broader editorial and release-specific checks as the content model grows.

Planning these features does not establish a release date or guarantee their final design.

Outside the current Wombat implementation

The following ideas require a separate application or service layer and do not exist in this repository:

• user accounts and authentication;
• browser-based document editing;
• drafts, reviews, and publishing permissions;
• collaborative authoring;
• hosted customer documentation portals;
• a managed DocsHub service;
• billing or subscriptions; and
• direct SnapDock-to-DocsHub publishing.

These ideas belong to the longer-term Capybara direction. They should not be described as current Wombat capabilities.

Current architectural flow

Markdown / Nunjucks / front matter
                 │
                 ▼
        Eleventy + Markdown-it
                 │
          ┌──────┴──────┐
          ▼             ▼
    Static HTML     search-index.json
          │             │
          └──────┬──────┘
                 ▼
       Browser UI and local search
                 │
                 ▼
      GitHub Actions → host branch

Wombat’s role

Wombat is the working static foundation of DocsHub. Its purpose is to make the existing documentation accurate, searchable, consistently rendered, and easy to publish through the project’s controlled deployment pipeline. It is also preparing the content structure, validation, discovery, and publishing pipelines required by Capybara’s planned public-submission workflow. Future platform features can build on that foundation, but they are not part of the current product until their implementation and user guidance exist in this repository.