@wbc-ui2/press

v1.0.0-r01

Published

13 days ago

wb-press — a content-graph mini-framework: feed it one navigation.js and it renders the whole site (menu, sidebar, routes, content) through WBC. Built on @wbc-ui2/core's link/route engine.

0High
0Medium
0Low

wissemb11

wbc-ui2 wbc content-graph navigation dynamic-routes documentation mini-framework search ssg sitemap rss dark-mode

Why?

A docs framework usually ships a fixed folder convention, a fixed theme, and a fixed set of plugins. wb-press ships none of that. It takes one description of your site — a content graph — and renders the entire thing through the @wbc-ui2/core link/route engine.

The navigation graph is the site. Every link — menu, sidebar, in-content — flows through WBC's resolveWbLinkTarget, so:

./file.md references become dynamic routes (auto-registered, refresh-safe),
existing route names / paths navigate,
external URLs / anchors stay plain <a>.

No special page folder. No theme lock-in. No plugin registry. A page body is any WBC content; the shell is one WBC item you can recompose surface-by-surface.

What is @wbc-ui2/press?

A Vue 2.7+ mini-framework built on @wbc-ui2/core. You give it a navigation graph and a few options; it returns a mounted app — routes, a composable shell, per-route <head> meta, full-text search, and SSG output.

createWbPress(navigation, options) → { app, router, store, graph, mount }

Usage

Level 1 — a two-page site

// src/main.js (host app)
import { createWbPress } from '@wbc-ui2/press';
import navigation from './config/navigation';

createWbPress(navigation, {
  context: require.context('.', true),   // WBC file resolution (host-provided)
}).mount('#app');

// src/config/navigation.js — the single source of truth
import { defineNavigation } from '@wbc-ui2/press';

export default defineNavigation([
  { name: 'Home',  path: '/',      item: './content/home.md',  label: 'Home',  meta: { title: 'Home' } },
  { name: 'About', path: '/about', item: './content/about.md', label: 'About', meta: { title: 'About' } },
]);

Level 2 — the node shape

{ name, path, item, meta, label, icon, menu?, sidebar?, children? }

item — any WBC content rendered as the page body. Not just markdown:
- md file ('./guide.md') — prose
- media file — image / video / audio ('./demo.mp4')
- office file — docx / xlsx / pptx
- code / text / style file — syntax-highlighted ('./snippet.ts')
- Vue SFC ('./Counter.vue') — a live component
- URL — external link / YouTube embed ('https://youtu.be/…')
- simple WBC string — 'text | classes | link'
- generalized WBC object / array — { comp, options }
The same applies to link targets (to): one WBC engine renders every type.
meta — SEO / <head> source (title, description, og:*, …).
label — string or { en, fr, … } shown in menu / sidebar.

Level 3 — non-standard entries are WBC items

A navigation entry that is not a standard node — a string, an array, or an object without path/children — is treated as a WBC item and auto-wrapped into a route via transformNonStandard: path/name are generated, component is WBC, props.item is the original entry.

export default defineNavigation([
  'text-|red|./content/home.md',                 // → /wbc/content/home  (WBCHome)
  'static-text',                                  // → /wbc/static-text   (WBCStaticText)
  { comp:'li', options:{ html:'…|red|./x.md' } }, // → /wbc/li            (WBCLi)
  { name:'Home', path:'/', item:'./content/home.md', meta:{ title:'Home' } }, // standard
]);

See the link/route reference: wbc-links-routes.md.

Extensions

All opt-in via createWbPress options, all driven by the content graph:

| Option | Adds | |---|---| | search | navbar full-text search (graph + raw markdown → MiniSearch) | | prevNext | previous / next page footer (graph order) | | toc | sticky on-page "On this page" right rail | | logo / darkMode | app-bar brand logo + persistent dark-mode toggle | | languages | navbar language switcher — sets WBC's lg (multilingual labels / meta / content) | | headingAnchors | hover # permalinks on headings | | callouts | GitHub-style alert blockquotes (> [!TIP] …) → admonitions | | readingTime / lastUpdated / editLink | per-page meta strip + "Edit this page" | | footer | site-wide footer, host-defined, rendered through WBC | | writeSsg({ feed }) | Atom feed.xml alongside the sitemap |

createWbPress(navigation, {
  context: require.context('.', true),
  search: { content: import.meta.glob('./content/**/*.md', { query: '?raw', import: 'default', eager: true }) },
  prevNext: true, toc: true, headingAnchors: true, callouts: true,
  readingTime: true, lastUpdated: true,
  logo: 'mdi-book-open-variant', darkMode: { default: 'auto' },
  languages: ['en', 'fr', 'ar'],
  editLink: { repoUrl: 'https://github.com/you/repo', basePath: 'docs/src' },
}).mount('#app');

Components in Markdown — drop any registered component into a page with its props using Component__~{ …props } (e.g. ). See the docs.

Public API

| export | purpose | |---|---| | createWbPress(navigation, options) | factory → { app, router, store, graph, mount } | | defineNavigation(nav) / validateNavigation(nav) | author / validate the graph | | graphToRoutes(graph, WBC) | graph → vue-router records (runtime sink) | | flattenGraph(nodes) | tree → flat page list (shared by routes + SSG) | | createAppShell(graph, opts) / renderMenu / renderSidebar | the WBC shell — one WBC item composed from a surface registry via an output layout (appbar/menubar/sidebar/rSide/content/footer…) | | applyMeta(route, opts) | runtime <head> meta | | SearchBox / buildSearchIndex(graph, content) | navbar full-text search (MiniSearch) | | PageNav / PageToc / PageMeta / EditLink / LangMenu | shell extension components | | ContentEnhancer / collectHeadings / slugify | heading anchors + callouts | | buildPageMeta(graph, opts) / resolveContent(opts) | per-route reading time / updated / edit URL | | @wbc-ui2/press/ssg → buildManifest, buildSitemap, buildFeed, writeSsg, includedRoutes | SSG output |

Roadmap

Phase 0–1 (done): package + runtime engine (content graph → routes, WBC shell, meta).
Phase 2 (done): build-time route manifest + sitemap.xml + Atom feed.xml + dual-mode resolver.
Shell extensions (done): search, prev/next, TOC, logo, dark mode, language switcher, heading anchors, callouts, reading time, last-updated, edit link.
Phase 3: SSG / pre-render via vite-ssg, targeting the Vue 3 line (@wbc-ui3).

Ecosystem

@wbc-ui2/press is one package of the @wbc-ui2 monorepo — every package builds on @wbc-ui2/core's "UI as Data" engine: code, chart, dataviewer, latex, mermaid, gis, alert, press.

This product is planned, built, and released through the wb-flow workflow.

License

The free-tier build (published to npm as @wbc-ui2/press) is licensed under the MIT License — see LICENSE.

The pro-tier build (dist-pro/) is distributed under a separate commercial license. Contact the copyright holder for commercial licensing.