Integrations

Silen keeps integrations explicit. Plugins run trusted build or client code, analytics is configured at the site layer, and Ask AI talks only to an endpoint you operate. None of these features requires importing internal Silen files.

Plugins

Plugins are ordered factories in .silen/config.ts. Use them for MDX processors, Vite integrations, page metadata, head entries, client setup, or post-build output:

import { defineConfig } from '@aicode-nexus/silen'
import readingTime from './plugins/reading-time'

export default defineConfig({
  plugins: [[readingTime, { wordsPerMinute: 250 }]],
})

Every plugin has a name; add an id for multiple instances. Hooks execute in configuration order and failures report the plugin identity plus hook. Read the complete plugin lifecycle.

Analytics

Analytics is theme-independent and production-only. Configure Google, Baidu, or an ordered custom provider:

analytics: [
  { provider: 'google', id: 'G-XXXXXXXXXX' },
  { provider: 'baidu', id: 'site-id' },
]

Silen reports the initial page and later client-route changes while ignoring hash-only navigation. Google users should disable automatic history-change pageviews in Enhanced Measurement to avoid duplicates. A custom provider can load external or inline scripts and listen for silen:pageview. Scripts are trusted public code; never embed credentials.

Ask AI

Ask AI is an optional theme endpoint, not a bundled model provider:

themeConfig: {
  ai: { endpoint: '/api/ask' },
}

Ask AI request

Silen sends an HTTP POST with Content-Type: application/json. The request contract is exactly:

interface AskAiRequest {
  route: string
  selectedText?: string
  messages: Array<{
    role: 'user' | 'assistant'
    content: string
  }>
}

selectedText is optional; omit it when the reader has not selected content. Messages can include prior user and assistant turns. A concrete request is:

{
  "route": "/guide/",
  "selectedText": "pnpm silen init docs",
  "messages": [
    { "role": "user", "content": "How do I start?" },
    { "role": "assistant", "content": "Install the package first." }
  ]
}

Ask AI response

Return a successful streaming response with either Content-Type: application/x-ndjson or Content-Type: application/ndjson. This NDJSON response writes one JSON object per line. The event shapes are text { type: 'text', value: string }, citation { type: 'citation', title: string, url: string }, and error { type: 'error', message: string }:

{"type":"text","value":"Install with pnpm."}
{"type":"citation","title":"Quick start","url":"/guide/"}
{"type":"error","message":"Unable to answer."}

Silen supplies an AbortSignal to the request and aborts a superseded stream or a stream whose dialog closes. Treat that signal and the disconnected HTTP request as cancellation: stop upstream provider work and release resources.

Your endpoint owns server-side authentication. Keep provider keys and raw provider errors on the server, and return a safe public failure instead. With no endpoint, Silen emits no Ask AI control and no Ask AI client bundle.

For deterministic, provider-free AI access, use the generated artifacts and local MCP workspace.