Overhaul documentation site with new content, search & improved styling by fliptation · Pull Request #688 · unchainedshop/unchained

fliptation · 2026-02-24T23:16:11Z

Add new documentation sections: AI Integration (MCP server, Admin Copilot, FAQ), GraphQL API concepts,
permissions guide, and developer guides (server setup, testing, seed data, contributing)
Redesign docs homepage with feature highlights and quick-start links, replacing the old markdown landing page
Rework sidebar organization, UI styles (dark mode, navbar, collapsed chevron), and remove footer
Fix incorrect API signatures, enum values, and import paths across existing module docs (messaging, bookmarks,
countries, currencies, events, languages, orders, warehousing)
Add doc metadata headers, robots.txt, and SEO improvements
Add Playwright screenshot automation script for retaking admin-ui screenshots
Add custom dark-mode logo and improved CSS (syntax highlighting, sidebar, search bar)

- Install docusaurus-plugin-llms to auto-generate llms.txt and llms-full.txt - Create AI Integration section with MCP server reference, Admin Copilot setup guide, and AI FAQ - Update sidebar with new section between Plugins and Troubleshooting - Redirect old enable-copilot page to new ai-integration/admin-copilot - Add cross-reference from general FAQ to AI FAQ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This pull request adds comprehensive AI Integration documentation and enables automatic generation of llms.txt files for LLM discovery. The changes introduce a new top-level documentation section that consolidates and expands the existing AI capabilities documentation.

Changes:

Installs docusaurus-plugin-llms (v0.2.2) to auto-generate /llms.txt and /llms-full.txt for LLM documentation discovery
Creates new AI Integration documentation section with 4 pages: overview, MCP server reference, Admin Copilot setup guide, and AI FAQ
Redirects the old enable-copilot page to the new AI Integration section for backward compatibility
Adds cross-reference from general FAQ to AI-specific FAQ
Applies minor formatting improvements to sidebar configuration (multi-line to single-line array formatting)

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`docs/package.json`	Adds `docusaurus-plugin-llms` as devDependency
`docs/package-lock.json`	Installs plugin v0.2.2 with dependencies (gray-matter, minimatch, yaml)
`docs/docusaurus.config.js`	Configures llms plugin with title, description, and options for generating documentation files
`docs/sidebars.js`	Adds AI Integration section between Plugins and Troubleshooting; applies formatting cleanup to array declarations
`docs/docs/platform-configuration/enable-copilot.md`	Converts to redirect page pointing to new AI Integration location
`docs/docs/troubleshooting/faq.md`	Adds cross-reference to AI Integration FAQ
`docs/docs/ai-integration/index.md`	Overview page with architecture diagram and surface comparison table
`docs/docs/ai-integration/mcp-server.md`	Complete MCP server reference including authentication, tools, resources, and client connection examples
`docs/docs/ai-integration/admin-copilot.md`	Setup guide for Admin UI Copilot with OpenAI, Anthropic, and self-hosted LLM examples
`docs/docs/ai-integration/ai-faq.md`	Comprehensive FAQ covering MCP server, Admin Copilot, and integration patterns

Files not reviewed (1)

docs/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add descriptive frontmatter to many docs (admin-ui, ai-integration, quick-start, platform-configuration, plugins, and extend docs) to improve SEO and page summaries. Enrich plugin tables (delivery, payment, pricing, workers) with extra columns and guidance to clarify use cases and integration types. Update docusaurus.config to include rootContent overview, enable color-mode switching, and add site-wide docs settings. Add Google Inter font and extensive custom CSS refinements (sidebar, navbar, typography, pagination, breadcrumbs, footer) to improve readability and navigation. Add environment-variables frontmatter and create static/robots.txt to allow crawling by common bots.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…odule APIs Addresses documentation gap analysis by adding 6 new pages (GraphQL API reference, permissions reference, server setup, testing, seed data, contributing) and enriching 8 existing module pages with API method documentation and usage examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Remove non-existent CARD/LOCAL from PaymentProviderType/DeliveryProviderType enums - Fix permission action count from 126 to 111 - Fix configureRoles and checkResolver import paths to use namespace exports - Fix bookmarks replaceUserId signature to positional args - Fix events getReport signature to use dateRange/types params Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Redesign homepage with card-based layout and feature grid - Update color palette to neutral dark/light theme - Add dark mode logo variant - Hide external link icons across navbar and footer - Add homepage CSS classes for hero, cards, grid, and features - Add Playwright for screenshot automation - Improve sidebar, navbar, and content typography Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 57 out of 59 changed files in this pull request and generated 7 comments.

Files not reviewed (1)

docs/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T00:47:40Z

docs/docs/guides/testing.md

+```typescript
+import { describe, it, assert } from 'node:test';
+
+describe('My Custom Payment Adapter', () => {
+  const adapter = MyPaymentAdapter;
+
+  it('should have correct key', () => {
+    assert.equal(adapter.key, 'shop.example.payment.custom');


The examples import assert from node:test, but Node’s test runner does not export assert (it comes from node:assert/strict). As written, these snippets won’t run when copy-pasted. Split the imports (e.g., describe/it from node:test and assert from node:assert/strict).

Copilot · 2026-02-25T00:47:40Z

docs/docs/ai-integration/admin-copilot.md

+```typescript
+import { connect } from '@unchainedshop/api/fastify';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+
+// ... after creating fastify instance and unchained platform ...
+
+if (process.env.OPENAI_COMPAT_API_URL && process.env.OPENAI_COMPAT_MODEL) {
+  const provider = createOpenAICompatible({
+    name: 'local',
+    baseURL: process.env.OPENAI_COMPAT_API_URL,
+  });
+  connect(fastify, engine, {
+    chat: {
+      model: provider.chatModel(process.env.OPENAI_COMPAT_MODEL),
+    },
+  });
+}
+```
+
+### OpenAI
+
+```typescript
+import { connect } from '@unchainedshop/api/fastify';
+import { openai } from '@ai-sdk/openai';
+
+// ... after creating fastify instance and unchained platform ...
+
+if (process.env.OPENAI_API_KEY) {
+  connect(fastify, engine, {
+    chat: {
+      model: openai('gpt-4-turbo'),


The setup snippets call connect(fastify, engine, ...), but engine isn’t defined anywhere in the examples. In the repo examples, the second argument is the platform returned from startPlatform(...). Rename the variable in the snippets (or show its declaration) to keep the docs copy-pasteable.

Copilot · 2026-02-25T00:47:41Z

docs/scripts/take-screenshots.ts

+  const { data: cartData } = await gql(page, `
+    mutation {
+      createCart(orderNumber: "DOC-SCREENSHOT-001") { _id orderNumber }
+    }
+  `);
+  const orderId = cartData.createCart._id;
+


The screenshot seed step creates a cart with a fixed orderNumber ("DOC-SCREENSHOT-001"). If this script is run more than once against the same database, the mutation may fail due to uniqueness constraints. Consider generating a unique order number per run (timestamp/UUID) or deleting/reusing an existing cart tagged for screenshots.

Copilot · 2026-02-25T00:47:41Z

docs/src/css/custom.css

+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+
 /* You can override the default Infima variables here. */
 :root {
-  --ifm-color-primary: #2e8555;
-  --ifm-color-primary-dark: #29784c;
-  --ifm-color-primary-darker: #277148;
-  --ifm-color-primary-darkest: #205d3b;
-  --ifm-color-primary-light: #33925d;
-  --ifm-color-primary-lighter: #359962;
-  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI',
+    Roboto, Oxygen, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;


Importing Inter via @import from fonts.googleapis.com introduces a runtime third‑party request (performance + privacy/CSP implications, and it can break in offline/air‑gapped environments). If external fonts aren’t acceptable for this docs site, consider self-hosting the font files (or using system fonts only) and removing the remote @import.

Copilot · 2026-02-25T00:47:41Z

docs/docs/admin-ui/work-queue.md

@@ -1,6 +1,7 @@
 ---
 sidebare_position: 15


Frontmatter key sidebare_position looks like a typo; Docusaurus expects sidebar_position, so this page may not be ordered/registered as intended in the sidebar. Rename the key to sidebar_position (keeping the same numeric value).

Suggested change

sidebare_position: 15

sidebar_position: 15

Copilot · 2026-02-25T00:47:41Z

docs/docs/platform-configuration/modules/warehousing.md

+| `create` | `doc` | Create a warehousing provider |
+| `update` | `warehousingProviderId, doc` | Update provider |
+| `delete` | `providerId` | Delete provider |


modules.warehousing.delete takes a warehousingProviderId (see e.g. removeWarehousingProvider mutation), but this table lists the argument as providerId. Please align the docs with the actual API to avoid confusion / copy-paste errors.

Copilot · 2026-02-25T00:47:42Z

docs/docs/platform-configuration/messaging.md

+  return [
    {
-      type: "MESSAGE",
-      retries: 0,
+      type: 'EMAIL',
      input: {
-        template: "ERROR_REPORT",
-        userId,
-        error: 'Required more information',
-        resolverName: 'someResolver'
-        ...params,
+        to: 'admin@example.com',
+        subject: `New order #${order.orderNumber}`,
+        text: `Order total: ${order.pricing?.total}`,
      },
    },
-  );
-  return true;
+    {
+      type: 'TWILIO',
+      input: {
+        to: '+41791234567',
+        text: `New order #${order.orderNumber}`,
+      },
+    },


The multi-channel template example omits required/expected fields (from for EMAIL and from for TWILIO). This conflicts with the TemplateResolver output types in @unchainedshop/core and with the Twilio worker requirement (needs from unless TWILIO_SMS_FROM is set). Update the examples to include from (or explicitly note when env vars provide defaults) so the snippets are copy-paste safe for TypeScript users.

@copilot open a new pull request to apply changes based on this feedback

Add new Docusaurus homepage (docs/docs/index.md), remove legacy pages/src homepage, and update assets. Rework sidebars.js to a consolidated mainSidebar with reorganized sections (Documentation, Guides, Admin UI, Plugins, etc.) and remove separate guides/admin sidebars. Update docusaurus.config.js to add local search plugin and adjust navbar items. Revise custom.css to support the new sidebar layout, icons, homepage card styles and search input styling. Adjust Playwright baseURL to http://localhost:3000 and include generated test-results artifacts; update two homepage asset images.

Copilot · 2026-02-25T01:18:21Z

@fliptation I've opened a new pull request, #689, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

Copilot reviewed 60 out of 64 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

docs/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T01:26:26Z

docs/test-results/.last-run.json

+{
+  "status": "failed",
+  "failedTests": [
+    "5ba4e90f3b27cd29068c-bf4ef5f0cd9ddd2deea1"
+  ]
+}


These look like Playwright test artifacts from a local run. Committing .last-run.json will create noisy diffs and can expose local test IDs; it should be removed from the repo and added to an ignore rule (e.g., docs/test-results/).

Copilot · 2026-02-25T01:26:26Z

docs/test-results/take-screenshots.ts-take-all-admin-ui-screenshots-chromium/error-context.md

+# Page snapshot
+
+```yaml
+- generic [ref=e1]:
+  - generic [ref=e2]:
+    - region "Notifications Alt+T"
+    - img "Logo" [ref=e4]
+    - button "auto" [ref=e7]:
+      - img [ref=e8]
+    - generic [ref=e11]:
+      - heading "Log in to your account" [level=2] [ref=e13]
+      - generic [ref=e16]:
+        - generic [ref=e17]:
+          - generic "Username/Email" [ref=e18]
+          - textbox "Username/Email" [active] [ref=e19]
+        - button "Continue" [ref=e21]:
+          - img [ref=e23]
+          - text: Continue
+        - generic [ref=e25]:
+          - text: Create new account?
+          - link "Sign up" [ref=e26] [cursor=pointer]:
+            - /url: /sign-up/
+  - button "Open Next.js Dev Tools" [ref=e32] [cursor=pointer]:
+    - img [ref=e33]
+  - alert [ref=e36]
+```


This file appears to be an auto-generated Playwright error snapshot under docs/test-results/. Test output directories generally shouldn’t be versioned; please remove this from the PR and ignore docs/test-results/ so future CI/local runs don’t produce tracked files.

Introduce comprehensive CSS for code blocks: container, content wrapper, code area, always-visible title bar and copy button, language labels (JS/TS/GraphQL/JSON/etc.), explicit title handling, and dark-theme adjustments to improve readability and UX. Also remove the 'GraphQL Playground' nav item from docs/docusaurus.config.js (likely obsolete).

Add CSS rule to correct hover/active states for search dropdown suggestions in dark theme. Targets elements with class names containing 'suggestion' or 'cursor' under [data-theme='dark'] and applies a subtle translucent white background and inherited text color to improve visibility and contrast.

Introduce styles for the search dropdown in docs CSS: add shadow/spacing CSS variables, border, border-radius and dark-theme border-color. Also add sizing for the no-results icon and padding/font-size for no-results text to improve appearance and spacing in both light and dark themes (docs/src/css/custom.css).

Adjust code block styling in docs CSS for better contrast and scoping. Replace several subtle rgba backgrounds with explicit hex colors for light/dark modes (e.g. #f6f8fa, #eff1f3, #1e1e2e, #181825), increase dark-theme border opacity (0.10 -> 0.12 and 0.06 -> 0.08), and narrow the button group selector to children of codeBlockContent to avoid affecting unrelated button groups. (docs/src/css/custom.css)

Increase bottom padding on sidebar .menu for more whitespace, add explicit .navbar__toggle svg dimensions, and standardize markdown heading font sizes (h1–h6) with a reduced top margin for the first h1. These tweaks improve visual rhythm and ensure consistent navbar toggle sizing across viewports.

fliptation requested a review from Copilot February 24, 2026 23:16

Copilot started reviewing on behalf of fliptation February 24, 2026 23:16 View session

fliptation requested a review from Mikearaya February 24, 2026 23:17

Copilot AI reviewed Feb 24, 2026

View reviewed changes

fliptation and others added 6 commits February 25, 2026 00:28

Fix sidebar collapsed chevron direction to point right

25e98d6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Remove footer and darken dark-mode navbar background

65a8255

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fliptation requested a review from Copilot February 25, 2026 00:39

Copilot started reviewing on behalf of fliptation February 25, 2026 00:39 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Copilot AI mentioned this pull request Feb 25, 2026

docs: fix multi-channel template example missing required from fields #689

Closed

fliptation requested review from Copilot and pozylon February 25, 2026 01:20

Copilot started reviewing on behalf of fliptation February 25, 2026 01:21 View session

fliptation changed the title ~~Add AI Integration docs section and llms.txt generation~~ Add AI Integration docs section and llms.txt generation and revamp docs styles, add search Feb 25, 2026

Copilot AI reviewed Feb 25, 2026

View reviewed changes

fliptation changed the title ~~Add AI Integration docs section and llms.txt generation and revamp docs styles, add search~~ Overhaul documentation site with new content, redesigned homepage & improved styling Feb 25, 2026

fliptation added 3 commits February 25, 2026 02:36

fliptation changed the title ~~Overhaul documentation site with new content, redesigned homepage & improved styling~~ Overhaul documentation site with new content, search, redesigned homepage & improved styling Feb 25, 2026

fliptation added 2 commits February 25, 2026 02:56

fliptation changed the title ~~Overhaul documentation site with new content, search, redesigned homepage & improved styling~~ Overhaul documentation site with new content, search & improved styling Feb 25, 2026

pozylon merged commit 9da32ce into master Feb 25, 2026
4 checks passed

Conversation

fliptation commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

fliptation Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 25, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fliptation commented Feb 24, 2026 •

edited

Loading