@inovus-medical/docs 0.5.0 → 0.8.0

package/README.md

@@ -22,7 +22,17 @@ npx inovus-docs dev      # build + serve + watch (http://localhost:8788)
 npx inovus-docs serve    # serve an existing dist/
 ```
 
-Flags: `--root <dir>` `--in <docs>` `--out <dist>` `--port <n>`.
+Flags: `--root <dir>` `--in <docs>` `--out <dist>` `--port <n>` `--theme <name>`.
+
+## Themes
+
+Named themes each include light and dark variants. Built-ins: `default`, `totum`.
+
+Selection (first match wins): `--theme` > `DOCS_THEME` env var > `"theme"` in
+`docs.config.json` > `default`. On Cloudflare, set `DOCS_THEME` under Worker →
+**Settings → Build → Variables** (build-time).
+
+Local preview: `npx inovus-docs dev --theme totum`.
 
 ## What it does
 

package/assets/themes/totum.css

@@ -0,0 +1,112 @@
+/* Totum theme — light + dark (selected via DOCS_THEME / --theme / docs.config.json) */
+
+:root {
+  --accent: #00bbff;
+  --accent-hover: #0099cc;
+  --bg: #f9fafb;
+  --bg-soft: #ffffff;
+  --bg-sidebar: #ffffff;
+  --text: #0f172a;
+  --text-soft: #64748b;
+  --border: #e2e8f0;
+  --code-bg: #f1f5f9;
+  --header-bg: #000000;
+  --header-text: #ffffff;
+  --header-muted: #d1d5db;
+  --radius: 12px;
+}
+
+[data-theme='dark'] {
+  --accent: #00bbff;
+  --accent-hover: #33ccff;
+  --bg: #0a0a0a;
+  --bg-soft: #141414;
+  --bg-sidebar: #141414;
+  --text: #f1f5f9;
+  --text-soft: #94a3b8;
+  --border: #262626;
+  --code-bg: #1a1a1a;
+  --header-bg: #000000;
+  --header-text: #ffffff;
+  --header-muted: #9ca3af;
+}
+
+/* ---------- Header (black in both modes) ---------- */
+[data-docs-theme='totum'] .site-header {
+  background: var(--header-bg);
+  border-bottom-color: #1f2937;
+  color: var(--header-text);
+  backdrop-filter: none;
+}
+[data-docs-theme='totum'] .site-header .brand {
+  color: var(--header-text);
+}
+[data-docs-theme='totum'] .site-header .header-link {
+  color: var(--header-muted);
+}
+[data-docs-theme='totum'] .site-header .header-link:hover {
+  color: var(--header-text);
+}
+[data-docs-theme='totum'] .site-header .vis-badge {
+  color: var(--header-muted);
+  border-color: #374151;
+}
+[data-docs-theme='totum'] .site-header .vis-private {
+  color: #fbbf24;
+  border-color: color-mix(in srgb, #fbbf24 45%, #374151);
+}
+[data-docs-theme='totum'] .site-header .vis-public {
+  color: #4ade80;
+  border-color: color-mix(in srgb, #4ade80 45%, #374151);
+}
+[data-docs-theme='totum'] .site-header .theme-toggle,
+[data-docs-theme='totum'] .site-header .menu-toggle {
+  color: var(--header-text);
+  border-color: #374151;
+}
+[data-docs-theme='totum'] .site-header .theme-toggle:hover,
+[data-docs-theme='totum'] .site-header .menu-toggle:hover {
+  background: #1f2937;
+}
+[data-docs-theme='totum'] .site-header #search-input {
+  background: #1f2937;
+  border-color: #374151;
+  color: var(--header-text);
+}
+[data-docs-theme='totum'] .site-header #search-input::placeholder {
+  color: #9ca3af;
+}
+[data-docs-theme='totum'] .site-header #search-input:focus {
+  outline: 2px solid color-mix(in srgb, var(--accent) 55%, transparent);
+  border-color: var(--accent);
+}
+
+/* ---------- Nav / surfaces ---------- */
+[data-docs-theme='totum'] .sidebar {
+  border-right-color: var(--border);
+}
+[data-docs-theme='totum'] .nav-link {
+  border-radius: 999px;
+}
+[data-docs-theme='totum'] .nav-link.active {
+  color: var(--accent);
+  background: color-mix(in srgb, var(--accent) 14%, transparent);
+  font-weight: 600;
+}
+[data-docs-theme='totum'] .pager-link {
+  border-radius: var(--radius);
+  background: var(--bg-soft);
+}
+[data-docs-theme='totum'] .pager-link:hover {
+  border-color: var(--accent);
+}
+[data-docs-theme='totum'] .prose pre,
+[data-docs-theme='totum'] .mermaid-wrap {
+  border-radius: var(--radius);
+}
+[data-docs-theme='totum'] .search-results {
+  border-radius: var(--radius);
+}
+[data-docs-theme='totum'] a:hover {
+  color: var(--accent-hover);
+}

package/bin/cli.js

@@ -31,6 +31,7 @@ const root = path.resolve(flags.root || process.cwd())
 const inDir = flags.in // undefined -> build() auto-detects (docs/ or repo root)
 const outDir = flags.out || 'dist'
 const port = Number(flags.port || 8788)
+const theme = typeof flags.theme === 'string' ? flags.theme : undefined
 
 async function run() {
   if (cmd === 'init') {
@@ -50,18 +51,18 @@ async function run() {
   }
 
   if (cmd === 'build') {
-    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir })
+    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir, theme })
     console.log(`✓ Built ${pageCount} page(s) from ${contentDir === '.' ? 'repo root' : contentDir + '/'} -> ${path.relative(process.cwd(), outPath) || outPath}`)
     return
   }
 
   if (cmd === 'dev') {
-    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir })
+    const { pageCount, outPath, contentDir } = await build({ root, inDir, outDir, theme })
     console.log(`✓ Built ${pageCount} page(s) from ${contentDir === '.' ? 'repo root' : contentDir + '/'}`)
     const { port: actual } = await serve({ dir: outPath, port })
     const busy = actual !== port ? `  (port ${port} was busy)` : ''
     console.log(`→ Serving http://localhost:${actual}${busy}  (watching ${contentDir === '.' ? 'repo root' : contentDir + '/'} for changes)`)
-    watchAndRebuild({ root, inDir: contentDir, outDir })
+    watchAndRebuild({ root, inDir: contentDir, outDir, theme })
     return
   }
 
@@ -76,9 +77,9 @@ async function run() {
   console.error(
     `Unknown command: ${cmd}\n` +
       `Usage:\n` +
-      `  inovus-docs init   [--name <n>] [--title <t>] [--public] [--repo <url>] [--no-readme] [--force]\n` +
-      `  inovus-docs build  [--root .] [--in <dir>] [--out dist]\n` +
-      `  inovus-docs dev    [--port 8788]\n` +
+      `  inovus-docs init   [--name <n>] [--title <t>] [--content <dir>] [--public] [--repo <url>] [--no-readme] [--force]\n` +
+      `  inovus-docs build  [--root .] [--in <dir>] [--out dist] [--theme <name>]\n` +
+      `  inovus-docs dev    [--port 8788] [--theme <name>]\n` +
       `  inovus-docs serve  [--port 8788]`
   )
   process.exit(1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inovus-medical/docs",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Turn a folder of markdown into a themed, Cloudflare-ready docs site.",
   "type": "module",
   "bin": {

package/src/build.js

@@ -10,11 +10,43 @@ import { buildRouteMap, rewriteLinks } from './links.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const ASSET_SRC = path.join(__dirname, '..', 'assets')
+const THEMES_DIR = path.join(ASSET_SRC, 'themes')
 
 const DEFAULT_IGNORE_DIRS = new Set([
   'node_modules', '.git', '.github', '.svn', '.hg', '.cache', '.vscode', '.idea', '.wrangler'
 ])
 
+/** List named themes shipped as assets/themes/<name>.css (plus built-in "default"). */
+async function listThemes() {
+  const names = new Set(['default'])
+  try {
+    const entries = await fs.readdir(THEMES_DIR)
+    for (const e of entries) {
+      if (e.toLowerCase().endsWith('.css')) names.add(e.slice(0, -4).toLowerCase())
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err
+  }
+  return names
+}
+
+/**
+ * Resolve theme: CLI --theme > DOCS_THEME env > docs.config.json > "default".
+ * Unknown names warn and fall back to default.
+ */
+async function resolveTheme({ themeFlag, config }) {
+  const raw = themeFlag ?? process.env.DOCS_THEME ?? config.theme ?? 'default'
+  const name = String(raw).trim().toLowerCase() || 'default'
+  const available = await listThemes()
+  if (!available.has(name)) {
+    console.warn(
+      `⚠ Unknown theme "${name}" — falling back to default. Available: ${[...available].sort().join(', ')}`
+    )
+    return 'default'
+  }
+  return name
+}
+
 // Only these non-markdown files get copied into the site. Keeps a whole-repo scan from
 // shipping source, lockfiles, or secrets (e.g. .env) to a public site.
 const MEDIA_EXT = new Set([
@@ -87,8 +119,10 @@ function routeToFile(outPath, route) {
   return path.join(outPath, rel, 'index.html')
 }
 
-export async function build({ root = process.cwd(), inDir, outDir = 'dist' } = {}) {
+export async function build({ root = process.cwd(), inDir, outDir = 'dist', theme: themeFlag } = {}) {
   const config = await loadConfig(root)
+  const theme = await resolveTheme({ themeFlag, config })
+  config.theme = theme
   const outPath = path.join(root, outDir)
   const ignore = makeIgnore(config, path.basename(outPath))
 
@@ -190,6 +224,10 @@ export async function build({ root = process.cwd(), inDir, outDir = 'dist' } = {
     await fs.copyFile(path.join(ASSET_SRC, name), path.join(assetsOut, name))
   }
 
+  if (theme !== 'default') {
+    await fs.copyFile(path.join(THEMES_DIR, `${theme}.css`), path.join(assetsOut, 'theme.css'))
+  }
+
   for (const file of assetFiles) {
     const rel = path.relative(contentRoot, file)
     const dest = path.join(outPath, rel)

package/src/config.js

@@ -5,7 +5,10 @@ const DEFAULTS = {
   title: 'Documentation',
   description: '',
   logo: null,
-  accent: '#2563eb',
+  // null = use the theme's accent (base styles.css sets --accent for default).
+  accent: null,
+  // Named theme (each has light + dark). Overridden by DOCS_THEME / --theme.
+  theme: 'default',
   repo: null,
   editBase: null,
   visibility: 'private',

package/src/init.js

@@ -112,6 +112,9 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   const visibility = flags.public ? 'public' : 'private'
   const repoUrl = flags.repo || remote.httpsUrl || null
   const force = flags.force === true
+  // Content root: --content <dir>, else auto-set "docs" when docs/ exists, else omit (auto-detect at build).
+  let content = typeof flags.content === 'string' ? flags.content.trim() : null
+  if (!content && (await fileExists(path.join(root, 'docs')))) content = 'docs'
 
   const created = []
   const skipped = []
@@ -123,6 +126,7 @@ export async function init({ root = process.cwd(), flags = {} } = {}) {
   } else {
     const cfg = { title, description: '', visibility }
     if (repoUrl) cfg.repo = repoUrl
+    if (content) cfg.content = content
     await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + '\n')
     created.push('docs.config.json')
   }

package/src/layout.js

@@ -74,16 +74,19 @@ function header(config) {
 
 function shell({ config, pageTitle, description, navHtml, main }) {
   const accent = config.accent ? `<style>:root{--accent:${esc(config.accent)}}</style>` : ''
+  const docsTheme = (config.theme && config.theme !== 'default') ? config.theme : 'default'
+  const themeLink =
+    docsTheme !== 'default' ? '<link rel="stylesheet" href="/_assets/theme.css">\n' : ''
   const desc = description || config.description || ''
   return `<!doctype html>
-<html lang="en" data-theme="light">
+<html lang="en" data-theme="light" data-docs-theme="${esc(docsTheme)}">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>${esc(pageTitle)}</title>
 ${desc ? `<meta name="description" content="${esc(desc)}">` : ''}
 <link rel="stylesheet" href="/_assets/styles.css">
-${accent}
+${themeLink}${accent}
 <script>(function(){try{var t=localStorage.getItem('theme');if(!t)t=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';document.documentElement.setAttribute('data-theme',t);}catch(e){}})();</script>
 </head>
 <body>

package/src/watch.js

@@ -10,7 +10,7 @@ const IGNORED = /(^|[\\/])(node_modules|\.git|dist)([\\/]|$)/
  * ignored so writing dist/ doesn't trigger an infinite rebuild loop (matters when the
  * content root is the whole repo).
  */
-export function watchAndRebuild({ root, inDir, outDir }) {
+export function watchAndRebuild({ root, inDir, outDir, theme }) {
   const watchPath = inDir === '.' ? root : path.join(root, inDir)
   const outBase = path.basename(outDir)
   let timer = null
@@ -23,7 +23,7 @@ export function watchAndRebuild({ root, inDir, outDir }) {
       if (building) return
       building = true
       try {
-        const { pageCount } = await build({ root, inDir: inDir === '.' ? '.' : inDir, outDir })
+        const { pageCount } = await build({ root, inDir: inDir === '.' ? '.' : inDir, outDir, theme })
         console.log(`↻ Rebuilt ${pageCount} page(s)`)
       } catch (err) {
         console.error('Build failed:', err.message)