@lupinum/ginko-docs 0.3.0-rc.4 → 0.3.0-rc.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +44 -135
  2. package/nuxt.config.ts +1 -1
  3. package/package.json +4 -3
package/README.md CHANGED
@@ -1,169 +1,78 @@
1
- # Ginko Docs
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/lupinum-dev/ginko-docs/main/docs/public/web-app-manifest-512x512.png" width="128" alt="Ginko Docs icon">
3
+ </p>
2
4
 
3
- Ginko Docs is a Nuxt layer for focused documentation sites. It combines Ginko Content collections with a documentation shell, navigation, search, localization, SEO, social images, optional blog routes, and agent-readable Markdown surfaces.
5
+ <h1 align="center">@lupinum/ginko-docs</h1>
4
6
 
5
- ## Requirements
7
+ <p align="center">Add a complete documentation experience to a Nuxt application through one reusable layer.</p>
6
8
 
7
- - Node.js `^22.18.0 || ^24.11.0 || >=26.0.0`
8
- - Nuxt `>=4.4.7 <5`
9
- - Vue `^3.5.35`
10
- - Vue Router `^5.1.0`
11
- - Ginko Content `>=0.4.0-rc.1 <0.5.0`
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/@lupinum/ginko-docs"><img src="https://img.shields.io/npm/v/@lupinum/ginko-docs?color=00DC82" alt="npm version"></a>
11
+ <a href="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/ginko-docs/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
12
+ <a href="https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
13
+ </p>
12
14
 
13
- ## Install
15
+ > [!WARNING]
16
+ > This package is pre-1.0. Install `0.3.0-rc.5` from the npm `next` channel for evaluation.
14
17
 
15
- Install the layer and its Ginko Content peer:
18
+ ## Purpose
16
19
 
17
- ```bash
18
- pnpm add -D @lupinum/ginko-docs@0.3.0-rc.4 @lupinum/ginko-content@0.4.0-rc.1
19
- ```
20
+ Use this package when a Nuxt application needs documentation routes, navigation, search, localization, metadata, social images, feedback, and agent-readable content. The layer provides the interface while the consuming application keeps ownership of its content and identity.
20
21
 
21
- Keep the public identity in one shared value:
22
+ ## Requirements
22
23
 
23
- ```json [site.json]
24
- {
25
- "name": "Example Docs",
26
- "description": "Documentation for Example.",
27
- "url": "https://docs.example.com"
28
- }
29
- ```
24
+ - Node.js 22.18, 24.11, or 26 and later maintenance releases
25
+ - Nuxt 4.5.1 or later in the Nuxt 4 line
26
+ - Vue 3.5.35 or later
27
+ - Ginko Content 0.4 prerelease or later in the 0.4 line
30
28
 
31
- Extend the layer and configure the canonical origin:
29
+ ## Installation
32
30
 
33
- ```ts [nuxt.config.ts]
34
- import site from "./site.json" with { type: "json" };
31
+ ```bash
32
+ pnpm add -D @lupinum/ginko-docs@0.3.0-rc.5 @lupinum/ginko-content@0.4.0-rc.2
33
+ ```
35
34
 
35
+ ```ts
36
36
  export default defineNuxtConfig({
37
37
  extends: ["@lupinum/ginko-docs"],
38
- site: { url: site.url },
39
- i18n: { baseUrl: site.url },
38
+ site: { url: "https://docs.example.com" },
39
+ i18n: { baseUrl: "https://docs.example.com" },
40
40
  });
41
41
  ```
42
42
 
43
- Define the content collections in `content.config.ts`:
43
+ ## Quick start
44
44
 
45
- ```ts [content.config.ts]
45
+ ```ts
46
46
  import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
47
- import site from "./site.json" with { type: "json" };
48
47
 
49
48
  export default defineGinkoDocsConfig({
50
- site,
49
+ site: {
50
+ name: "Example Docs",
51
+ description: "Documentation for Example.",
52
+ url: "https://docs.example.com",
53
+ },
51
54
  locales: ["en"],
52
55
  blog: false,
53
56
  });
54
57
  ```
55
58
 
56
- Single-locale documentation belongs in `content/docs`. Add a first page:
57
-
58
- ```md [content/docs/1.introduction.md]
59
- ---
60
- title: Introduction
61
- description: Learn what Example does and how to use it.
62
- ---
63
-
64
- Example solves ...
65
- ```
66
-
67
- The bare `/docs` route redirects to the first navigable document.
68
-
69
- ## Set the public identity
70
-
71
- Presentation settings live in `app/app.config.ts`:
72
-
73
- ```ts [app/app.config.ts]
74
- import site from "../site.json";
75
-
76
- export default defineAppConfig({
77
- ginkoDocs: {
78
- site: {
79
- name: { en: site.name },
80
- description: { en: site.description },
81
- url: site.url,
82
- logo: { light: "/logo.svg", dark: "/logo-dark.svg" },
83
- docsSidebarSwitcher: "tabs",
84
- lupinumAttribution: true,
85
- },
86
- nav: { links: "auto" },
87
- banner: { enabled: false, id: "default", showOnLanding: true },
88
- feedback: { enabled: false },
89
- toc: { depth: 3 },
90
- },
91
- });
92
- ```
93
-
94
- Localized values use `{ en, de? }`. Use English as the default locale; supported content layouts are English-only and bilingual English/German.
95
-
96
- Set the production URL once in `site.json`, then pass it to the content configuration, app configuration, Nuxt Site configuration, and Nuxt i18n `baseUrl`. JSON keeps the shared identity portable across each configuration loader. The layer uses it for canonical links, structured data, social cards, and agent catalogs.
97
-
98
- ## Enable the blog
99
-
100
- Set `blog: true` in `defineGinkoDocsConfig`. That single option creates the `blog` and `authors` collections and keeps the blog routes in the generated Nuxt application.
101
-
102
- Blog posts are flat Markdown files under `content/2.blog` for an English-only site, or the corresponding locale directory for a bilingual site. Each post requires `title`, `description`, `date`, `readingTime`, and an `author` reference. Author records live under `authors` and require `slug`, `name`, `role`, `bio`, and `avatar`.
103
-
104
- ## Customize presentation
105
-
106
- Use Nuxt's normal application directories. A consumer can replace `app/pages/index.vue`, layouts, or a stable shell component by providing the same component name:
107
-
108
- - `SiteHeader`, `SiteFooter`, `SiteBanner`, `SiteLogoMark`
109
- - `SiteLocaleSwitcher`, `SiteInteractionLayer`, `DocsSidebar`
110
-
111
- Load consumer theme CSS from an app plugin so it follows the layer styles without replacing Nuxt's merged `css` array.
112
-
113
- To add an authored MDC component, extend the exported tag map and declare its static render policy:
114
-
115
- ```ts [nuxt.config.ts]
116
- import { ginkoDocsComponentTags } from "@lupinum/ginko-docs/components";
117
-
118
- export default defineNuxtConfig({
119
- content: {
120
- componentPolicy: {
121
- components: {
122
- "api-playground": {
123
- kind: "block",
124
- props: {
125
- method: { type: "string", required: true },
126
- path: { type: "string", required: true },
127
- },
128
- slots: ["default"],
129
- media: null,
130
- },
131
- },
132
- },
133
- markdown: {
134
- tags: {
135
- ...ginkoDocsComponentTags,
136
- "api-playground": "MdcApiPlayground",
137
- },
138
- },
139
- },
140
- });
141
- ```
142
-
143
- Register the Vue component globally because Markdown resolves component targets dynamically. Register a serializer through `@lupinum/ginko-content/agent-registry` when copied and raw Markdown needs a representation other than the default XML-style component output.
144
-
145
- ## Agent and discovery surfaces
59
+ Put Markdown files in `content/docs`. Open `/docs` after the Nuxt server starts.
146
60
 
147
- Every deployment can include the prerendered routes and assets:
61
+ ## Exports
148
62
 
149
- - `/raw/**.md`
150
- - `/llms.txt` and `/llms-full.txt`
151
- - localized LLM catalogs
152
- - sitemap, robots, and PNG social images
63
+ - `@lupinum/ginko-docs` is the Nuxt layer entry.
64
+ - `@lupinum/ginko-docs/content` exports `defineGinkoDocsConfig`.
65
+ - `@lupinum/ginko-docs/app-config` exports application configuration types.
66
+ - `@lupinum/ginko-docs/components` exports the public MDC component contract.
153
67
 
154
- A Nitro server also provides request-time `Accept: text/markdown` negotiation, response link headers, and `/mcp`. The MCP server exposes read-only `list-pages` and `get-page` tools. Plain static hosting cannot provide those request-time behaviors.
68
+ ## Documentation
155
69
 
156
- The `markdownActions` app settings change the page menu only; they do not disable agent routes.
70
+ Read the [Ginko Docs documentation](https://ginko-docs.lupinum.com) and the [root README](https://github.com/lupinum-dev/ginko-docs#readme).
157
71
 
158
- ## Public exports
72
+ ## Support and security
159
73
 
160
- | Export | Contents |
161
- | -------------------------------- | ------------------------------------------------------------- |
162
- | `@lupinum/ginko-docs` | Nuxt layer entry |
163
- | `@lupinum/ginko-docs/content` | `defineGinkoDocsConfig` |
164
- | `@lupinum/ginko-docs/app-config` | App-configuration types |
165
- | `@lupinum/ginko-docs/components` | Tag map, component names, component policy, and related types |
74
+ Use [GitHub issues](https://github.com/lupinum-dev/ginko-docs/issues) or the [Lupinum OSS Discord](https://discord.gg/RPH6SeA36N) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/ginko-docs/security/policy).
166
75
 
167
76
  ## License
168
77
 
169
- [MIT](./LICENSE)
78
+ Released by [Lupinum OG](https://lupinum.com) under the [MIT License](https://github.com/lupinum-dev/ginko-docs/blob/main/LICENSE).
package/nuxt.config.ts CHANGED
@@ -55,7 +55,7 @@ export default defineNuxtConfig({
55
55
  },
56
56
  mcp: {
57
57
  name: "Ginko Docs",
58
- version: "0.3.0-rc.4",
58
+ version: "0.3.0-rc.5",
59
59
  },
60
60
  components: {
61
61
  dirs: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lupinum/ginko-docs",
3
- "version": "0.3.0-rc.4",
3
+ "version": "0.3.0-rc.5",
4
4
  "description": "A Nuxt documentation layer powered by Ginko Content.",
5
5
  "keywords": [
6
6
  "content",
@@ -14,6 +14,7 @@
14
14
  "url": "https://github.com/lupinum-dev/ginko-docs/issues"
15
15
  },
16
16
  "license": "MIT",
17
+ "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
17
18
  "repository": {
18
19
  "type": "git",
19
20
  "url": "git+https://github.com/lupinum-dev/ginko-docs.git",
@@ -84,8 +85,8 @@
84
85
  "zod": "^4.4.3"
85
86
  },
86
87
  "peerDependencies": {
87
- "@lupinum/ginko-content": ">=0.4.0-rc.1 <0.5.0",
88
- "nuxt": ">=4.4.7 <5",
88
+ "@lupinum/ginko-content": ">=0.4.0-rc.2 <0.5.0",
89
+ "nuxt": ">=4.5.1 <5",
89
90
  "vue": "^3.5.35",
90
91
  "vue-router": "^5.1.0"
91
92
  },