@oneie/plugin-docs 0.1.0

package/LICENSE

@@ -0,0 +1,86 @@
+# ONE License (Version 1.0)
+
+Copyright (c) 2024-2026 one.ie
+
+## Maximum Freedom, One Obligation
+
+This license empowers you with complete commercial freedom to use, reuse, modify, sell and resell the software, AI and data, at any price you wish.
+
+No usage limits. No royalty fees. Just pure, unrestricted ability to innovate and profit from the software.
+
+You are free to run ONE locally, on your own servers, in the cloud and at the edge.
+
+## You Receive
+
+### Unlimited Rights
+
+You have unrestricted rights to use, modify, license, sublicense, distribute, sell, resell and monetize the Software without restrictions, subject only to the Brand Requirement below.
+
+### Permitted Actions
+
+Including, but not limited to:
+
+- Commercial use and integration into any systems
+- Creation and sale of derivative works
+- Providing software as a service
+- AI training and content generation
+- Patenting innovations based on the Software
+- Open source applications and integrations
+
+### License Compatibility
+
+This license is compatible with all major open-source licenses, including:
+
+- MIT License
+- Apache License
+- GNU General Public License (GPL)
+- BSD Licenses
+- Mozilla Public License
+
+### Perpetual Rights
+
+These rights are granted in perpetuity and are irrevocable, provided the Brand Requirement is maintained.
+
+## Intellectual Property
+
+- We retain ownership of the original Software and data.
+- You own any modifications you make.
+- You never have to share your code or data.
+
+## Brand Requirement
+
+The only obligation is:
+
+- Don't remove the ONE brand, logo, and link to https://one.ie/ from the deployed product.
+
+To remove the Brand Requirement — white-label, no visible ONE branding — obtain the
+**ONE Enterprise License** (see `LICENSE-ENTERPRISE.md` or contact agent@one.ie).
+
+## Liability and Warranty
+
+The Software and data is provided "AS IS". We bear no liability for its use.
+
+## Termination
+
+This license terminates if you remove or hide the ONE brand, logo, or link without
+holding a current ONE Enterprise License.
+
+## Governing Law and Disputes
+
+This license is governed by the laws of Ireland. The parties will attempt to resolve disputes through good-faith negotiation. If necessary, disputes will proceed to mediation under the Mediators' Institute of Ireland rules, and then to binding arbitration under the Arbitration Act 2010, seated in Dublin, conducted in English.
+
+---
+
+This license is designed to maximize freedom to innovate and profit. There is no copyleft requirement to share any code, making it suitable for enterprise use.
+
+## Enterprise Solutions
+
+Building something big? We're here to help:
+
+- **Free** — use every feature with the ONE brand link in the footer
+- **White-label** — remove the brand requirement (ONE Enterprise License)
+- **Custom** — white-label solutions tailored to your needs
+- **Enterprise** — full support and deployment assistance
+- **Training** — help getting your team started
+
+Contact agent@one.ie to share your needs · Learn at https://one.ie/learn · Agents: https://one.ie/llms.txt

package/README.md

@@ -0,0 +1,151 @@
+# @oneie/plugin-docs
+
+ONE docs plugin — Astro content collection with sidebar nav, search, code blocks, and versioning. Ships full source to your repo (free tier).
+
+## Install
+
+```bash
+bun add @oneie/plugin-docs
+```
+
+## one.config.ts
+
+```ts
+import { defineOne } from '@oneie/frontend'
+import { docs } from '@oneie/plugin-docs'
+
+export default defineOne({
+  plugins: [
+    docs({
+      docsDir: 'src/content/docs',       // default
+      injectRoutes: true,                 // default
+      editBaseUrl: 'https://github.com/your-org/your-repo/edit/main',
+      sidebar: [
+        { folder: 'getting-started', label: 'Getting Started', icon: '🚀' },
+        { folder: 'guides',          label: 'Guides',          icon: '📖' },
+        { folder: 'reference',       label: 'Reference',       icon: '📐' },
+      ],
+    }),
+  ],
+})
+```
+
+## Content collection schema
+
+Create `src/content/config.ts` (or add to your existing one):
+
+```ts
+import { defineCollection, z } from 'astro:content'
+
+const docs = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    /** Numeric sort order within the folder. Lower = first. */
+    order: z.number().optional(),
+    /** Optional category tag for filtering */
+    category: z.string().optional(),
+  }),
+})
+
+export const collections = { docs }
+```
+
+Files live at `src/content/docs/**/*.md` or `.mdx`. The first path segment becomes the sidebar folder:
+
+```
+src/content/docs/
+  getting-started/
+    introduction.md      # slug: getting-started/introduction
+    installation.md      # slug: getting-started/installation
+  guides/
+    deployment.md        # slug: guides/deployment
+  reference/
+    api.md               # slug: reference/api
+```
+
+## Usage — [slug].astro
+
+Create `src/pages/docs/[slug].astro`:
+
+```astro
+---
+import { getCollection, getEntry } from 'astro:content'
+import DocsLayout from '@oneie/plugin-docs/DocsLayout.astro'
+
+export async function getStaticPaths() {
+  const docs = await getCollection('docs')
+  return docs.map((entry) => ({
+    params: { slug: entry.id },
+    props: { entry },
+  }))
+}
+
+const { entry } = Astro.props
+const allDocs = await getCollection('docs')
+const { Content, headings } = await entry.render()
+---
+
+<DocsLayout
+  entry={entry}
+  entries={allDocs}
+  headings={headings}
+  editBaseUrl="https://github.com/your-org/your-repo/edit/main/src/content/docs"
+  sidebar={[
+    { folder: 'getting-started', label: 'Getting Started' },
+    { folder: 'guides', label: 'Guides' },
+    { folder: 'reference', label: 'Reference' },
+  ]}
+>
+  <Content />
+</DocsLayout>
+```
+
+## Docs landing page — /docs/index.astro
+
+```astro
+---
+import DocsIndex from '@oneie/plugin-docs/DocsIndex.astro'
+---
+
+<DocsIndex
+  title="Documentation"
+  description="Everything you need to get up and running."
+/>
+```
+
+## Sidebar order
+
+Folders render in the order declared in the `sidebar` array. Entries within each folder sort by `order` (frontmatter) then alphabetically by title. Folders not listed in `sidebar` append after the configured ones.
+
+## editBaseUrl — GitHub edit links
+
+Set `editBaseUrl` to the raw path of your docs directory on GitHub:
+
+```
+https://github.com/your-org/your-repo/edit/main/src/content/docs
+```
+
+An "Edit this page on GitHub" link appears at the bottom of every doc, pointing to `editBaseUrl/entry.id`.
+
+## Components (standalone use)
+
+```tsx
+import { DocSearch } from '@oneie/plugin-docs/DocSearch.tsx'
+import { SidebarDocs } from '@oneie/plugin-docs/SidebarDocs.tsx'
+import { CodeBlock } from '@oneie/plugin-docs/CodeBlock.tsx'
+
+// Search bar
+<DocSearch value={currentSearch} placeholder="Search…" />
+
+// Sidebar (requires React state for collapsible folders)
+<SidebarDocs entries={entries} currentSlug={slug} sidebar={sidebarConfig} />
+
+// Code block with copy button
+<CodeBlock code={`const x = 1`} language="ts" filename="example.ts" />
+```
+
+## License
+
+ONE License — full commercial use, keep the ONE brand link. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@oneie/plugin-docs",
+  "version": "0.1.0",
+  "description": "ONE docs — Astro content collection with sidebar nav, search, code blocks, and versioning",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./DocSearch.tsx": "./src/DocSearch.tsx",
+    "./SidebarDocs.tsx": "./src/SidebarDocs.tsx",
+    "./CodeBlock.tsx": "./src/CodeBlock.tsx",
+    "./DocsLayout.astro": "./src/DocsLayout.astro",
+    "./DocsIndex.astro": "./src/DocsIndex.astro"
+  },
+  "peerDependencies": {
+    "astro": ">=6.0.0",
+    "@oneie/frontend": "*",
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "astro": "^6.2.2",
+    "react": "^19.0.0",
+    "typescript": "^5.7.3"
+  },
+  "peerDependenciesMeta": {
+    "@oneie/frontend": {
+      "optional": true
+    }
+  }
+}

package/src/CodeBlock.tsx

@@ -0,0 +1,75 @@
+import { useState } from 'react'
+import { Copy, Check } from 'lucide-react'
+
+export interface CodeBlockProps {
+  code: string
+  language?: string
+  filename?: string
+}
+
+/**
+ * CodeBlock — dark code block with optional filename tab, language badge, and copy button.
+ * Copy state resets after 2 seconds.
+ */
+export function CodeBlock({ code, language, filename }: CodeBlockProps) {
+  const [copied, setCopied] = useState(false)
+
+  async function handleCopy() {
+    try {
+      await navigator.clipboard.writeText(code)
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    } catch {
+      // Clipboard API unavailable — silently no-op
+    }
+  }
+
+  return (
+    <div className="group relative my-4 overflow-hidden rounded-lg border border-slate-800 bg-slate-950 text-sm">
+      {/* Top bar: filename tab + language badge */}
+      {(filename || language) && (
+        <div className="flex items-center justify-between border-b border-slate-800 px-4 py-2">
+          {filename ? (
+            <span className="font-mono text-xs text-slate-400">{filename}</span>
+          ) : (
+            <span />
+          )}
+          {language && (
+            <span className="rounded bg-slate-800 px-2 py-0.5 font-mono text-xs text-slate-400">
+              {language}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Language badge when no filename bar */}
+      {!filename && !language && null}
+
+      {/* Code content */}
+      <div className="relative overflow-x-auto p-4">
+        <pre className="m-0 font-mono text-sm leading-relaxed text-slate-100">
+          <code>{code}</code>
+        </pre>
+
+        {/* Copy button — appears on group hover */}
+        <button
+          onClick={handleCopy}
+          aria-label={copied ? 'Copied' : 'Copy code'}
+          className="absolute right-3 top-3 flex items-center gap-1.5 rounded border border-slate-700 bg-slate-800 px-2 py-1 text-xs text-slate-300 opacity-0 transition-all hover:bg-slate-700 hover:text-white group-hover:opacity-100"
+        >
+          {copied ? (
+            <>
+              <Check className="h-3.5 w-3.5 text-green-400" />
+              <span>Copied</span>
+            </>
+          ) : (
+            <>
+              <Copy className="h-3.5 w-3.5" />
+              <span>Copy</span>
+            </>
+          )}
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/DocSearch.tsx

@@ -0,0 +1,39 @@
+import { Search } from 'lucide-react'
+
+export interface DocSearchProps {
+  value?: string
+  placeholder?: string
+}
+
+/**
+ * DocSearch — form-based full-text search for the docs collection.
+ * Submits to /docs with ?search= preserving view/folder/tag params.
+ */
+export function DocSearch({ value = '', placeholder = 'Search docs…' }: DocSearchProps) {
+  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+    e.preventDefault()
+    const form = e.currentTarget
+    const input = form.elements.namedItem('search') as HTMLInputElement
+    const params = new URLSearchParams(window.location.search)
+    params.set('search', input.value)
+    // Preserve view/folder/tag but reset pagination
+    params.delete('page')
+    window.location.href = `/docs?${params.toString()}`
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="relative w-full max-w-sm">
+      <span className="pointer-events-none absolute inset-y-0 left-3 flex items-center text-muted-foreground">
+        <Search className="h-4 w-4" />
+      </span>
+      <input
+        type="search"
+        name="search"
+        defaultValue={value}
+        placeholder={placeholder}
+        className="h-9 w-full rounded-md border border-input bg-background pl-9 pr-3 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        aria-label="Search documentation"
+      />
+    </form>
+  )
+}

package/src/DocsIndex.astro

@@ -0,0 +1,119 @@
+---
+import { getCollection } from 'astro:content'
+
+export interface Props {
+  title?: string
+  description?: string
+}
+
+const {
+  title = 'Documentation',
+  description = 'Everything you need to get started.',
+} = Astro.props
+
+// Fetch all docs and group by folder
+const allDocs = await getCollection('docs')
+
+// Sort by order then title within each folder
+allDocs.sort((a, b) => {
+  const ao = (a.data as { order?: number }).order ?? 999
+  const bo = (b.data as { order?: number }).order ?? 999
+  if (ao !== bo) return ao - bo
+  return a.data.title.localeCompare(b.data.title)
+})
+
+// Group by first path segment
+const groups: Record<string, typeof allDocs> = {}
+for (const doc of allDocs) {
+  const folder = doc.id.includes('/') ? doc.id.split('/')[0] : '_root'
+  if (!groups[folder]) groups[folder] = []
+  groups[folder].push(doc)
+}
+
+const folderOrder = Object.keys(groups).filter((f) => f !== '_root')
+const rootDocs = groups['_root'] ?? []
+
+function folderLabel(key: string): string {
+  return key.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+}
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <slot name="head" />
+  </head>
+  <body class="bg-background text-foreground antialiased">
+    <slot name="header" />
+
+    <!-- Hero -->
+    <section class="border-b border-border bg-muted/30 px-6 py-16 text-center">
+      <h1 class="text-4xl font-bold tracking-tight">{title}</h1>
+      {description && (
+        <p class="mx-auto mt-4 max-w-xl text-lg text-muted-foreground">{description}</p>
+      )}
+    </section>
+
+    <!-- Doc groups grid -->
+    <main class="mx-auto max-w-screen-xl px-6 py-12">
+      <!-- Root-level docs (no folder) -->
+      {rootDocs.length > 0 && (
+        <div class="mb-10">
+          <ul class="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+            {rootDocs.map((doc) => (
+              <li>
+                <a
+                  href={`/docs/${doc.id}`}
+                  class="block rounded-lg border border-border bg-card p-4 text-sm hover:border-primary hover:bg-accent transition-colors"
+                >
+                  <span class="font-medium text-foreground">{doc.data.title}</span>
+                  {doc.data.description && (
+                    <span class="mt-1 block text-xs text-muted-foreground line-clamp-2">
+                      {doc.data.description}
+                    </span>
+                  )}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      <!-- Folder sections -->
+      <div class="space-y-12">
+        {folderOrder.map((folder) => {
+          const folderDocs = groups[folder]
+          if (!folderDocs?.length) return null
+          return (
+            <section>
+              <h2 class="mb-4 text-xl font-semibold text-foreground">{folderLabel(folder)}</h2>
+              <ul class="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+                {folderDocs.map((doc) => (
+                  <li>
+                    <a
+                      href={`/docs/${doc.id}`}
+                      class="block rounded-lg border border-border bg-card p-4 text-sm hover:border-primary hover:bg-accent transition-colors"
+                    >
+                      <span class="font-medium text-foreground">{doc.data.title}</span>
+                      {doc.data.description && (
+                        <span class="mt-1 block text-xs text-muted-foreground line-clamp-2">
+                          {doc.data.description}
+                        </span>
+                      )}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          )
+        })}
+      </div>
+    </main>
+
+    <slot name="footer" />
+  </body>
+</html>

package/src/DocsLayout.astro

@@ -0,0 +1,118 @@
+---
+import type { CollectionEntry, MarkdownHeading } from 'astro:content'
+import { SidebarDocs } from './SidebarDocs.tsx'
+import { DocSearch } from './DocSearch.tsx'
+
+export interface Props {
+  entry: CollectionEntry<'docs'>
+  entries: CollectionEntry<'docs'>[]
+  headings?: MarkdownHeading[]
+  editBaseUrl?: string
+  sidebar?: Array<{ folder: string; label: string; icon?: string }>
+}
+
+const { entry, entries, headings = [], editBaseUrl, sidebar } = Astro.props
+
+const searchQuery = Astro.url.searchParams.get('search') ?? ''
+
+// Flatten entries for the sidebar component
+const sidebarEntries = entries.map((e) => ({
+  slug: e.id,
+  data: { title: e.data.title, order: (e.data as { order?: number }).order },
+}))
+
+const editUrl = editBaseUrl ? `${editBaseUrl.replace(/\/$/, '')}/${entry.id}` : null
+
+// Filter headings to h2/h3 for TOC
+const tocHeadings = headings.filter((h) => h.depth === 2 || h.depth === 3)
+---
+
+<!doctype html>
+<html lang="en" class="h-full">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{entry.data.title}</title>
+    {entry.data.description && <meta name="description" content={entry.data.description} />}
+    <slot name="head" />
+  </head>
+  <body class="h-full bg-background text-foreground antialiased">
+    <!-- Top bar -->
+    <header class="sticky top-0 z-40 flex h-14 items-center gap-4 border-b border-border bg-background/95 px-6 backdrop-blur">
+      <a href="/docs" class="mr-4 text-sm font-semibold text-foreground hover:text-primary">
+        Docs
+      </a>
+      <div class="flex-1">
+        <DocSearch client:load value={searchQuery} />
+      </div>
+      <slot name="header-actions" />
+    </header>
+
+    <!-- Two-column layout -->
+    <div class="mx-auto flex max-w-screen-xl">
+      <!-- Sidebar: 280px fixed width -->
+      <aside class="sticky top-14 hidden h-[calc(100vh-3.5rem)] w-[280px] shrink-0 overflow-hidden border-r border-border lg:block">
+        <SidebarDocs
+          client:load
+          entries={sidebarEntries}
+          currentSlug={entry.id}
+          sidebar={sidebar}
+        />
+      </aside>
+
+      <!-- Main content -->
+      <main class="min-w-0 flex-1 px-8 py-10">
+        <div class="flex gap-8">
+          <!-- Prose area -->
+          <article class="min-w-0 flex-1">
+            <h1 class="mb-2 text-3xl font-bold tracking-tight">{entry.data.title}</h1>
+            {entry.data.description && (
+              <p class="mb-8 text-lg text-muted-foreground">{entry.data.description}</p>
+            )}
+            <div class="prose prose-slate dark:prose-invert max-w-none">
+              <slot />
+            </div>
+
+            <!-- Edit this page -->
+            {editUrl && (
+              <div class="mt-12 border-t border-border pt-6">
+                <a
+                  href={editUrl}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  class="text-sm text-muted-foreground hover:text-foreground"
+                >
+                  Edit this page on GitHub →
+                </a>
+              </div>
+            )}
+          </article>
+
+          <!-- TOC: right panel, hidden on mobile -->
+          {tocHeadings.length > 0 && (
+            <nav
+              aria-label="On this page"
+              class="sticky top-20 hidden h-fit w-52 shrink-0 xl:block"
+            >
+              <p class="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                On this page
+              </p>
+              <ul class="space-y-1 text-sm">
+                {tocHeadings.map((h) => (
+                  <li class={h.depth === 3 ? 'pl-3' : ''}>
+                    <a
+                      href={`#${h.slug}`}
+                      class="block text-muted-foreground hover:text-foreground transition-colors py-0.5"
+                    >
+                      {h.text}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          )}
+        </div>
+      </main>
+    </div>
+  </body>
+</html>

package/src/SidebarDocs.tsx

@@ -0,0 +1,151 @@
+import { useState } from 'react'
+import { ChevronDown, ChevronRight } from 'lucide-react'
+
+export interface DocEntry {
+  slug: string
+  data: {
+    title: string
+    order?: number
+  }
+}
+
+export interface SidebarFolder {
+  folder: string
+  label: string
+  icon?: string
+}
+
+export interface SidebarDocsProps {
+  entries: DocEntry[]
+  currentSlug: string
+  sidebar?: SidebarFolder[]
+}
+
+function groupByFolder(entries: DocEntry[]): Record<string, DocEntry[]> {
+  const groups: Record<string, DocEntry[]> = {}
+  for (const entry of entries) {
+    const folder = entry.slug.includes('/') ? entry.slug.split('/')[0] : '_root'
+    if (!groups[folder]) groups[folder] = []
+    groups[folder].push(entry)
+  }
+  // Sort entries within each folder by order then title
+  for (const folder of Object.keys(groups)) {
+    groups[folder].sort((a, b) => {
+      const ao = a.data.order ?? 999
+      const bo = b.data.order ?? 999
+      if (ao !== bo) return ao - bo
+      return a.data.title.localeCompare(b.data.title)
+    })
+  }
+  return groups
+}
+
+function FolderSection({
+  folderKey,
+  label,
+  icon,
+  entries,
+  currentSlug,
+}: {
+  folderKey: string
+  label: string
+  icon?: string
+  entries: DocEntry[]
+  currentSlug: string
+}) {
+  const hasActive = entries.some((e) => e.slug === currentSlug)
+  const [open, setOpen] = useState(hasActive || folderKey === '_root')
+
+  return (
+    <div className="mb-1">
+      {folderKey !== '_root' && (
+        <button
+          onClick={() => setOpen((o) => !o)}
+          className="flex w-full items-center gap-1.5 rounded px-2 py-1.5 text-sm font-semibold text-foreground hover:bg-accent transition-colors"
+          aria-expanded={open}
+        >
+          {icon && <span aria-hidden="true">{icon}</span>}
+          <span className="flex-1 text-left">{label}</span>
+          {open ? (
+            <ChevronDown className="h-3.5 w-3.5 text-muted-foreground" />
+          ) : (
+            <ChevronRight className="h-3.5 w-3.5 text-muted-foreground" />
+          )}
+        </button>
+      )}
+      {open && (
+        <ul className={folderKey !== '_root' ? 'ml-3 border-l border-border pl-2' : ''}>
+          {entries.map((entry) => {
+            const isActive = entry.slug === currentSlug
+            return (
+              <li key={entry.slug}>
+                <a
+                  href={`/docs/${entry.slug}`}
+                  className={[
+                    'block rounded px-2 py-1 text-sm transition-colors',
+                    isActive
+                      ? 'text-primary font-medium bg-accent'
+                      : 'text-muted-foreground hover:text-foreground hover:bg-accent',
+                  ].join(' ')}
+                  aria-current={isActive ? 'page' : undefined}
+                >
+                  {entry.data.title}
+                </a>
+              </li>
+            )
+          })}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+/**
+ * SidebarDocs — collapsible folder-grouped sidebar for the docs collection.
+ * Folder order follows the `sidebar` config array; unlisted folders append at the end.
+ */
+export function SidebarDocs({ entries, currentSlug, sidebar = [] }: SidebarDocsProps) {
+  const groups = groupByFolder(entries)
+
+  // Build ordered folder list: sidebar config first, then remaining folders
+  const configuredFolders = sidebar.map((s) => s.folder)
+  const remainingFolders = Object.keys(groups).filter(
+    (f) => !configuredFolders.includes(f) && f !== '_root',
+  )
+  const orderedFolders = [...configuredFolders, ...remainingFolders]
+
+  // Root entries (no folder) render first without a header
+  const rootEntries = groups['_root'] ?? []
+
+  return (
+    <nav
+      aria-label="Documentation navigation"
+      className="h-full overflow-y-auto py-4 pr-2 text-sm"
+    >
+      {rootEntries.length > 0 && (
+        <FolderSection
+          folderKey="_root"
+          label=""
+          entries={rootEntries}
+          currentSlug={currentSlug}
+        />
+      )}
+      {orderedFolders.map((folderKey) => {
+        const folderEntries = groups[folderKey]
+        if (!folderEntries?.length) return null
+        const config = sidebar.find((s) => s.folder === folderKey)
+        const label = config?.label ?? folderKey.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+        return (
+          <FolderSection
+            key={folderKey}
+            folderKey={folderKey}
+            label={label}
+            icon={config?.icon}
+            entries={folderEntries}
+            currentSlug={currentSlug}
+          />
+        )
+      })}
+    </nav>
+  )
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+import type { OnePluginFactory } from '@oneie/frontend'
+
+export interface SidebarFolder {
+  folder: string
+  label: string
+  icon?: string
+}
+
+export interface OneDocsConfig {
+  /** Directory where docs content lives. Default: 'src/content/docs' */
+  docsDir?: string
+  /** Whether to inject /docs and /docs/[slug] routes automatically. Default: true */
+  injectRoutes?: boolean
+  /** User-defined folder order and labels for the sidebar */
+  sidebar?: SidebarFolder[]
+  /** Base URL for "Edit this page" GitHub links, e.g. 'https://github.com/org/repo/edit/main' */
+  editBaseUrl?: string
+}
+
+export const docs: OnePluginFactory<OneDocsConfig> = (config = {}) => ({
+  name: 'plugin-docs',
+  tier: 'free',
+  config: undefined,
+  integration: undefined,
+  entitlement: undefined,
+})
+
+export type { OneDocsConfig as DocsConfig, SidebarFolder }

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "react",
+    "paths": {
+      "@/*": ["../../apps/web/src/*"]
+    }
+  },
+  "include": ["src"]
+}