svelte-docsmith 0.15.0 → 0.16.0
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.
- package/README.md +47 -14
- package/dist/buildtime/markdown-source.d.ts +11 -0
- package/dist/buildtime/markdown-source.js +48 -1
- package/dist/buildtime/props/extract.d.ts +6 -0
- package/dist/buildtime/props/extract.js +20 -9
- package/dist/buildtime/vite/agent-markdown.d.ts +43 -0
- package/dist/buildtime/vite/agent-markdown.js +204 -0
- package/dist/buildtime/vite/collect.d.ts +4 -1
- package/dist/buildtime/vite/collect.js +5 -2
- package/dist/buildtime/vite/extract.js +8 -3
- package/dist/buildtime/vite/index.js +79 -30
- package/dist/components/chrome/copy-button.svelte +4 -1
- package/dist/components/chrome/copy-button.svelte.d.ts +2 -0
- package/dist/components/docs/props-table.svelte +2 -4
- package/dist/components/docs/props-table.svelte.d.ts +1 -1
- package/dist/components/layouts/copy-page-menu.svelte +110 -17
- package/dist/components/layouts/copy-page-menu.svelte.d.ts +4 -0
- package/dist/components/layouts/docs-shell.svelte +7 -1
- package/dist/components/layouts/docs-shell.svelte.d.ts +1 -0
- package/dist/core/config.d.ts +9 -0
- package/dist/core/config.js +2 -1
- package/dist/core/extracted-props.d.ts +5 -0
- package/dist/core/extracted-props.js +8 -1
- package/dist/core/version.d.ts +4 -2
- package/dist/core/version.js +1 -1
- package/dist/generate/llms.d.ts +15 -0
- package/dist/generate/llms.js +6 -2
- package/dist/index.d.ts +1 -0
- package/dist/index.js +5 -0
- package/dist/mcp/connect.d.ts +17 -0
- package/dist/mcp/connect.js +40 -0
- package/dist/mcp/handler.d.ts +57 -0
- package/dist/mcp/handler.js +391 -0
- package/dist/mcp/tools.d.ts +81 -0
- package/dist/mcp/tools.js +196 -0
- package/package.json +1 -1
|
@@ -17,8 +17,8 @@
|
|
|
17
17
|
* `<PropsTable of={…}>` (see `../props/extract.js`).
|
|
18
18
|
*
|
|
19
19
|
* Reading the docs root lives in `./pages.js` and building each index from what
|
|
20
|
-
* it read lives in `./collect.js`; this file owns the
|
|
21
|
-
* the only layer that reports to the console.
|
|
20
|
+
* it read lives in `./collect.js`; this file owns the Vite plugins and the props
|
|
21
|
+
* extractor they share, and is the only layer that reports to the console.
|
|
22
22
|
*/
|
|
23
23
|
import fs from 'node:fs';
|
|
24
24
|
import path from 'node:path';
|
|
@@ -26,8 +26,9 @@ import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
|
|
|
26
26
|
import { checkVersions, resolveVersions } from '../../core/version.js';
|
|
27
27
|
import { ARCHIVE_MARKER, discoverArchives } from '../archives.js';
|
|
28
28
|
import { docsBaseFrom } from '../paths.js';
|
|
29
|
-
import { isPageFile, readSourcePages, withCommitDates } from './pages.js';
|
|
29
|
+
import { isPageFile, readSourcePages, titleOf, withCommitDates } from './pages.js';
|
|
30
30
|
import { contentIndex, llmsIndex, searchIndex } from './collect.js';
|
|
31
|
+
import { agentMarkdownFor } from './agent-markdown.js';
|
|
31
32
|
import { collectReleases } from './releases.js';
|
|
32
33
|
import { commitDates } from '../git.js';
|
|
33
34
|
import { createPropsExtractor } from '../props/extract.js';
|
|
@@ -41,7 +42,33 @@ import { checkFrontmatter } from './frontmatter-schema.js';
|
|
|
41
42
|
* ```
|
|
42
43
|
*/
|
|
43
44
|
export function docsmith(options = {}) {
|
|
44
|
-
|
|
45
|
+
const extractor = sharedPropsExtractor(options);
|
|
46
|
+
return [
|
|
47
|
+
contentIndexPlugin(options, extractor),
|
|
48
|
+
exampleSourcePlugin(options),
|
|
49
|
+
propsPlugin(extractor)
|
|
50
|
+
];
|
|
51
|
+
}
|
|
52
|
+
// Shared across `docsmith()` calls too: SvelteKit builds the client and the
|
|
53
|
+
// server in one process, and both import every props module. Sharing the
|
|
54
|
+
// extractor means one TypeScript program and one result cache for both.
|
|
55
|
+
const extractors = new Map();
|
|
56
|
+
function sharedPropsExtractor(options) {
|
|
57
|
+
let root = process.cwd();
|
|
58
|
+
return {
|
|
59
|
+
configure(next) {
|
|
60
|
+
root = next;
|
|
61
|
+
},
|
|
62
|
+
get() {
|
|
63
|
+
const key = `${root}\0${options.tsconfig ?? ''}`;
|
|
64
|
+
let extractor = extractors.get(key);
|
|
65
|
+
if (!extractor) {
|
|
66
|
+
extractor = createPropsExtractor({ root, tsconfig: options.tsconfig });
|
|
67
|
+
extractors.set(key, extractor);
|
|
68
|
+
}
|
|
69
|
+
return extractor;
|
|
70
|
+
}
|
|
71
|
+
};
|
|
45
72
|
}
|
|
46
73
|
// --- content / search / llms index --------------------------------------
|
|
47
74
|
const CONTENT_SPECIFIER = 'svelte-docsmith/content';
|
|
@@ -67,7 +94,7 @@ function warnAboutDocsRoot(contentDir, exists, indexed) {
|
|
|
67
94
|
` Add \`+page.md\` files with at least a \`title:\` in their frontmatter to populate the sidebar.`);
|
|
68
95
|
}
|
|
69
96
|
}
|
|
70
|
-
function contentIndexPlugin(options) {
|
|
97
|
+
function contentIndexPlugin(options, extractor) {
|
|
71
98
|
const contentDir = path.resolve(options.content ?? 'src/routes/docs');
|
|
72
99
|
const routesDir = path.resolve(options.routes ?? 'src/routes');
|
|
73
100
|
const versions = options.versions;
|
|
@@ -90,9 +117,31 @@ function contentIndexPlugin(options) {
|
|
|
90
117
|
` ${reason}\n` +
|
|
91
118
|
` Pages will render without a last-updated date, and sitemap entries without \`lastmod\`.`);
|
|
92
119
|
}));
|
|
120
|
+
// What agents read: each page as agent markdown, with its `LiveExample`s
|
|
121
|
+
// written out as code and its generated props tables as markdown tables.
|
|
122
|
+
// Resolving a page's imports needs the plugin context, so the load hook
|
|
123
|
+
// passes it in as `host`; props come from the shared extractor, so pages
|
|
124
|
+
// without a props import never load TypeScript.
|
|
125
|
+
const buildLlmsIndex = async (pages, host) => {
|
|
126
|
+
// Only the pages the index keeps (`llmsIndex` drops untitled ones), so a
|
|
127
|
+
// dropped page can't warn or load TypeScript. All at once, so the props
|
|
128
|
+
// extractor batches every page's components into one TypeScript update.
|
|
129
|
+
const indexed = pages.filter((page) => titleOf(page) !== undefined);
|
|
130
|
+
const built = await Promise.all(indexed.map((page) => agentMarkdownFor(page, host)));
|
|
131
|
+
const rewrites = new Map();
|
|
132
|
+
indexed.forEach((page, i) => {
|
|
133
|
+
const rewrite = built[i];
|
|
134
|
+
if (rewrite)
|
|
135
|
+
rewrites.set(page.file, rewrite);
|
|
136
|
+
});
|
|
137
|
+
return llmsIndex(pages, indexOptions, (content, page) => rewrites.get(page.file)?.(content) ?? content);
|
|
138
|
+
};
|
|
93
139
|
return {
|
|
94
140
|
name: 'docsmith-content',
|
|
95
141
|
enforce: 'pre',
|
|
142
|
+
configResolved(config) {
|
|
143
|
+
extractor.configure(config.root);
|
|
144
|
+
},
|
|
96
145
|
resolveId(id) {
|
|
97
146
|
if (id === CONTENT_SPECIFIER)
|
|
98
147
|
return VIRTUAL_CONTENT_ID;
|
|
@@ -141,7 +190,13 @@ function contentIndexPlugin(options) {
|
|
|
141
190
|
if (id === VIRTUAL_LLMS_ID) {
|
|
142
191
|
const { pages } = readSourcePages(contentDir);
|
|
143
192
|
watch(pages);
|
|
144
|
-
|
|
193
|
+
const docs = await buildLlmsIndex(pages, {
|
|
194
|
+
resolve: async (specifier, importer) => (await this.resolve(specifier, importer, { skipSelf: true }))?.id,
|
|
195
|
+
watch: (file) => this.addWatchFile(file),
|
|
196
|
+
warn: (message) => this.warn(message),
|
|
197
|
+
props: async (file) => (await extractProps(extractor, file, this)).markdown
|
|
198
|
+
});
|
|
199
|
+
return `export const docs = ${JSON.stringify(docs)};\n`;
|
|
145
200
|
}
|
|
146
201
|
if (id === VIRTUAL_CHANGELOG_ID) {
|
|
147
202
|
if (!changelogFile)
|
|
@@ -217,20 +272,29 @@ const PROPS_PREFIX = '\0docsmith-props:';
|
|
|
217
272
|
// Like the `?source` id, it must not end in `.svelte`.
|
|
218
273
|
const PROPS_EXT = '.docsmith-props';
|
|
219
274
|
const PROPS_SUFFIX = '?props';
|
|
220
|
-
// Shared across plugin instances: SvelteKit builds the client and the server in
|
|
221
|
-
// one process, and both import every props module. Sharing the extractor means
|
|
222
|
-
// one TypeScript program and one result cache for both.
|
|
223
|
-
const extractors = new Map();
|
|
224
275
|
// A cached result comes back as the same object; warn about it once, not once
|
|
225
|
-
// per build.
|
|
276
|
+
// per build (or once per props import and again for the llms index).
|
|
226
277
|
const warned = new WeakSet();
|
|
227
|
-
|
|
228
|
-
|
|
278
|
+
/**
|
|
279
|
+
* Extract one component's props from a plugin hook: watch the files they were
|
|
280
|
+
* read from, so editing one re-runs the hook, and pass on the warnings.
|
|
281
|
+
*/
|
|
282
|
+
async function extractProps(extractor, file, ctx) {
|
|
283
|
+
const result = await extractor.get().extract(file);
|
|
284
|
+
for (const watched of result.watchFiles)
|
|
285
|
+
ctx.addWatchFile(watched);
|
|
286
|
+
if (!warned.has(result))
|
|
287
|
+
for (const warning of result.warnings)
|
|
288
|
+
ctx.warn(warning);
|
|
289
|
+
warned.add(result);
|
|
290
|
+
return result;
|
|
291
|
+
}
|
|
292
|
+
function propsPlugin(extractor) {
|
|
229
293
|
return {
|
|
230
294
|
name: 'docsmith-props',
|
|
231
295
|
enforce: 'pre',
|
|
232
296
|
configResolved(config) {
|
|
233
|
-
|
|
297
|
+
extractor.configure(config.root);
|
|
234
298
|
},
|
|
235
299
|
async resolveId(id, importer) {
|
|
236
300
|
if (!id.endsWith('.svelte' + PROPS_SUFFIX))
|
|
@@ -244,22 +308,7 @@ function propsPlugin(options) {
|
|
|
244
308
|
if (!id.startsWith(PROPS_PREFIX))
|
|
245
309
|
return;
|
|
246
310
|
const file = id.slice(PROPS_PREFIX.length, -PROPS_EXT.length);
|
|
247
|
-
|
|
248
|
-
// every props import instead of being rebuilt per component.
|
|
249
|
-
const key = `${root}\0${options.tsconfig ?? ''}`;
|
|
250
|
-
let extractor = extractors.get(key);
|
|
251
|
-
if (!extractor) {
|
|
252
|
-
extractor = createPropsExtractor({ root, tsconfig: options.tsconfig });
|
|
253
|
-
extractors.set(key, extractor);
|
|
254
|
-
}
|
|
255
|
-
const result = await extractor.extract(file);
|
|
256
|
-
const { props, warnings, watchFiles } = result;
|
|
257
|
-
for (const watched of watchFiles)
|
|
258
|
-
this.addWatchFile(watched);
|
|
259
|
-
if (!warned.has(result))
|
|
260
|
-
for (const warning of warnings)
|
|
261
|
-
this.warn(warning);
|
|
262
|
-
warned.add(result);
|
|
311
|
+
const { props } = await extractProps(extractor, file, this);
|
|
263
312
|
return `export default ${JSON.stringify(props)};`;
|
|
264
313
|
}
|
|
265
314
|
};
|
|
@@ -7,16 +7,19 @@
|
|
|
7
7
|
const {
|
|
8
8
|
copied,
|
|
9
9
|
onclick,
|
|
10
|
+
label = 'Copy',
|
|
10
11
|
class: className
|
|
11
12
|
}: {
|
|
12
13
|
/** Whether the copy just succeeded — swaps the icon to a check. */
|
|
13
14
|
copied: boolean;
|
|
14
15
|
onclick: () => void;
|
|
16
|
+
/** Accessible name; name what is copied when a view has several buttons. */
|
|
17
|
+
label?: string;
|
|
15
18
|
class?: string;
|
|
16
19
|
} = $props();
|
|
17
20
|
</script>
|
|
18
21
|
|
|
19
|
-
<Button {onclick} variant="ghost" size="icon" aria-label=
|
|
22
|
+
<Button {onclick} variant="ghost" size="icon" aria-label={label} class="size-8 {className ?? ''}">
|
|
20
23
|
{#if copied}
|
|
21
24
|
<div in:fade={{ duration: 80 }}>
|
|
22
25
|
<Check class="text-emerald-500" />
|
|
@@ -2,6 +2,8 @@ type $$ComponentProps = {
|
|
|
2
2
|
/** Whether the copy just succeeded — swaps the icon to a check. */
|
|
3
3
|
copied: boolean;
|
|
4
4
|
onclick: () => void;
|
|
5
|
+
/** Accessible name; name what is copied when a view has several buttons. */
|
|
6
|
+
label?: string;
|
|
5
7
|
class?: string;
|
|
6
8
|
};
|
|
7
9
|
declare const CopyButton: import("svelte").Component<$$ComponentProps, {}, "">;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
<script lang="ts">
|
|
2
2
|
import type { Snippet } from 'svelte';
|
|
3
|
-
import type
|
|
3
|
+
import { propsCaption, type ExtractedProps } from '../../core/extracted-props.js';
|
|
4
4
|
import Prop from './prop.svelte';
|
|
5
5
|
|
|
6
6
|
const {
|
|
@@ -19,9 +19,7 @@
|
|
|
19
19
|
children?: Snippet;
|
|
20
20
|
} = $props();
|
|
21
21
|
|
|
22
|
-
const caption = $derived(
|
|
23
|
-
title ?? (of && of.name + (of.typeParameters.length ? `<${of.typeParameters.join(', ')}>` : ''))
|
|
24
|
-
);
|
|
22
|
+
const caption = $derived(title ?? (of && propsCaption(of)));
|
|
25
23
|
</script>
|
|
26
24
|
|
|
27
25
|
<!--
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { Snippet } from 'svelte';
|
|
2
|
-
import type
|
|
2
|
+
import { type ExtractedProps } from '../../core/extracted-props.js';
|
|
3
3
|
type $$ComponentProps = {
|
|
4
4
|
/** Caption. Defaults to the component's name when `of` is given. */
|
|
5
5
|
title?: string;
|
|
@@ -1,22 +1,32 @@
|
|
|
1
1
|
<script lang="ts">
|
|
2
2
|
import { BROWSER } from 'esm-env';
|
|
3
3
|
import { Button } from '../shadcn/button/index.js';
|
|
4
|
+
import * as Dialog from '../shadcn/dialog/index.js';
|
|
4
5
|
import * as DropdownMenu from '../shadcn/dropdown-menu/index.js';
|
|
6
|
+
import CopyButton from '../chrome/copy-button.svelte';
|
|
5
7
|
import Check from '@lucide/svelte/icons/check';
|
|
6
8
|
import ChevronDown from '@lucide/svelte/icons/chevron-down';
|
|
7
9
|
import Copy from '@lucide/svelte/icons/copy';
|
|
8
10
|
import FileText from '@lucide/svelte/icons/file-text';
|
|
9
11
|
import ArrowUpRight from '@lucide/svelte/icons/arrow-up-right';
|
|
12
|
+
import Plug from '@lucide/svelte/icons/plug';
|
|
10
13
|
import { join } from '../../utils/url.js';
|
|
14
|
+
import { editorSetups, mcpUrl } from '../../mcp/connect.js';
|
|
11
15
|
|
|
12
16
|
const {
|
|
13
17
|
path,
|
|
14
|
-
origin = ''
|
|
18
|
+
origin = '',
|
|
19
|
+
title = '',
|
|
20
|
+
mcp
|
|
15
21
|
}: {
|
|
16
22
|
/** The current page's normalized pathname, e.g. `/docs/intro`. */
|
|
17
23
|
path: string;
|
|
18
24
|
/** Absolute site origin for the AI deep links; falls back to `location.origin`. */
|
|
19
25
|
origin?: string;
|
|
26
|
+
/** Site title, which names the MCP server in the editor setup. */
|
|
27
|
+
title?: string;
|
|
28
|
+
/** Path (or absolute URL) of the site's MCP server; adds "Connect to your editor". */
|
|
29
|
+
mcp?: string;
|
|
20
30
|
} = $props();
|
|
21
31
|
|
|
22
32
|
// Convention: each page's markdown lives at `<path>.md`, served by the
|
|
@@ -24,28 +34,59 @@
|
|
|
24
34
|
const mdHref = $derived(`${path}.md`);
|
|
25
35
|
// Before hydration with no configured origin there is nothing to prefix, and
|
|
26
36
|
// `join` leaves the link site-relative rather than mangling it.
|
|
27
|
-
const
|
|
37
|
+
const siteOrigin = $derived(origin || (BROWSER ? location.origin : ''));
|
|
38
|
+
const absoluteMd = $derived(join(siteOrigin, mdHref));
|
|
28
39
|
const prompt = $derived(`Read ${absoluteMd} so I can ask questions about this page.`);
|
|
29
40
|
const chatgptHref = $derived(`https://chatgpt.com/?hints=search&q=${encodeURIComponent(prompt)}`);
|
|
30
41
|
const claudeHref = $derived(`https://claude.ai/new?q=${encodeURIComponent(prompt)}`);
|
|
31
42
|
|
|
43
|
+
const serverUrl = $derived(mcp ? mcpUrl(mcp, siteOrigin) : '');
|
|
44
|
+
const setups = $derived(serverUrl ? editorSetups(title, serverUrl) : []);
|
|
45
|
+
let connectOpen = $state(false);
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* A clipboard copy with its own "copied" timer: writes what `read` returns,
|
|
49
|
+
* then calls `show(true)`, and `show(false)` 1.5s after the latest copy.
|
|
50
|
+
* `navigator.clipboard` is undefined on insecure origins and can reject
|
|
51
|
+
* without permission; fail quietly so a copy button never throws.
|
|
52
|
+
*/
|
|
53
|
+
function clipboardCopy(failure: string) {
|
|
54
|
+
let timer: ReturnType<typeof setTimeout>;
|
|
55
|
+
return async (read: () => string | Promise<string>, show: (shown: boolean) => void) => {
|
|
56
|
+
try {
|
|
57
|
+
await navigator.clipboard.writeText(await read());
|
|
58
|
+
show(true);
|
|
59
|
+
clearTimeout(timer);
|
|
60
|
+
timer = setTimeout(() => show(false), 1500);
|
|
61
|
+
} catch (error) {
|
|
62
|
+
console.warn(`[svelte-docsmith] ${failure}`, error);
|
|
63
|
+
}
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
|
|
32
67
|
let copied = $state(false);
|
|
33
|
-
|
|
68
|
+
const copyPageText = clipboardCopy('copy page failed');
|
|
34
69
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
70
|
+
function copyPage() {
|
|
71
|
+
return copyPageText(
|
|
72
|
+
async () => {
|
|
73
|
+
const res = await fetch(mdHref);
|
|
74
|
+
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
|
|
75
|
+
return res.text();
|
|
76
|
+
},
|
|
77
|
+
(shown) => (copied = shown)
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// Which snippet in the connect dialog was just copied, to flip its icon.
|
|
82
|
+
let copiedSnippet = $state<string | null>(null);
|
|
83
|
+
const copySnippetText = clipboardCopy('copy to clipboard failed');
|
|
84
|
+
|
|
85
|
+
function copySnippet(key: string, text: string) {
|
|
86
|
+
return copySnippetText(
|
|
87
|
+
() => text,
|
|
88
|
+
(shown) => (copiedSnippet = shown ? key : null)
|
|
89
|
+
);
|
|
49
90
|
}
|
|
50
91
|
</script>
|
|
51
92
|
|
|
@@ -110,6 +151,58 @@
|
|
|
110
151
|
</a>
|
|
111
152
|
{/snippet}
|
|
112
153
|
</DropdownMenu.Item>
|
|
154
|
+
{#if serverUrl}
|
|
155
|
+
<DropdownMenu.Separator />
|
|
156
|
+
<DropdownMenu.Item onSelect={() => (connectOpen = true)}>
|
|
157
|
+
<Plug />
|
|
158
|
+
Connect to your editor
|
|
159
|
+
</DropdownMenu.Item>
|
|
160
|
+
{/if}
|
|
113
161
|
</DropdownMenu.Content>
|
|
114
162
|
</DropdownMenu.Root>
|
|
115
163
|
</div>
|
|
164
|
+
|
|
165
|
+
{#if serverUrl}
|
|
166
|
+
<Dialog.Root bind:open={connectOpen}>
|
|
167
|
+
<Dialog.Content class="max-h-[90vh] overflow-y-auto sm:max-w-lg">
|
|
168
|
+
<Dialog.Header>
|
|
169
|
+
<Dialog.Title>Connect to your editor</Dialog.Title>
|
|
170
|
+
<Dialog.Description>
|
|
171
|
+
Add this MCP server to your editor so its agent can search and read these docs.
|
|
172
|
+
</Dialog.Description>
|
|
173
|
+
</Dialog.Header>
|
|
174
|
+
<div class="grid gap-4">
|
|
175
|
+
<div class="grid gap-1.5">
|
|
176
|
+
<span class="font-medium">Server URL</span>
|
|
177
|
+
<div class="bg-muted flex items-center gap-2 rounded-md pl-3">
|
|
178
|
+
<code class="min-w-0 flex-1 truncate font-mono text-xs">{serverUrl}</code>
|
|
179
|
+
<CopyButton
|
|
180
|
+
label="Copy server URL"
|
|
181
|
+
copied={copiedSnippet === 'url'}
|
|
182
|
+
onclick={() => copySnippet('url', serverUrl)}
|
|
183
|
+
/>
|
|
184
|
+
</div>
|
|
185
|
+
</div>
|
|
186
|
+
{#each setups as { editor, file, code } (editor)}
|
|
187
|
+
<div class="grid gap-1.5">
|
|
188
|
+
<div class="flex items-baseline gap-2">
|
|
189
|
+
<span class="font-medium">{editor}</span>
|
|
190
|
+
{#if file}
|
|
191
|
+
<span class="text-muted-foreground font-mono text-xs">{file}</span>
|
|
192
|
+
{/if}
|
|
193
|
+
</div>
|
|
194
|
+
<div class="bg-muted relative rounded-md">
|
|
195
|
+
<pre class="overflow-x-auto p-3 pr-11 font-mono text-xs">{code}</pre>
|
|
196
|
+
<CopyButton
|
|
197
|
+
label="Copy {editor} setup"
|
|
198
|
+
copied={copiedSnippet === editor}
|
|
199
|
+
onclick={() => copySnippet(editor, code)}
|
|
200
|
+
class="absolute top-1 right-1"
|
|
201
|
+
/>
|
|
202
|
+
</div>
|
|
203
|
+
</div>
|
|
204
|
+
{/each}
|
|
205
|
+
</div>
|
|
206
|
+
</Dialog.Content>
|
|
207
|
+
</Dialog.Root>
|
|
208
|
+
{/if}
|
|
@@ -3,6 +3,10 @@ type $$ComponentProps = {
|
|
|
3
3
|
path: string;
|
|
4
4
|
/** Absolute site origin for the AI deep links; falls back to `location.origin`. */
|
|
5
5
|
origin?: string;
|
|
6
|
+
/** Site title, which names the MCP server in the editor setup. */
|
|
7
|
+
title?: string;
|
|
8
|
+
/** Path (or absolute URL) of the site's MCP server; adds "Connect to your editor". */
|
|
9
|
+
mcp?: string;
|
|
6
10
|
};
|
|
7
11
|
declare const CopyPageMenu: import("svelte").Component<$$ComponentProps, {}, "">;
|
|
8
12
|
type CopyPageMenu = ReturnType<typeof CopyPageMenu>;
|
|
@@ -81,6 +81,7 @@
|
|
|
81
81
|
* Show the "Copy page" split button on doc pages: copy the page as
|
|
82
82
|
* Markdown, view the raw `.md`, or open it in ChatGPT / Claude. Requires a
|
|
83
83
|
* catch-all `<path>.md` endpoint over the `svelte-docsmith/llms` index.
|
|
84
|
+
* With `config.mcp` set, the menu also offers "Connect to your editor".
|
|
84
85
|
*/
|
|
85
86
|
copyPage?: boolean;
|
|
86
87
|
/**
|
|
@@ -253,7 +254,12 @@
|
|
|
253
254
|
</span>
|
|
254
255
|
{/if}
|
|
255
256
|
{#if copyPage && view.entry}
|
|
256
|
-
<CopyPageMenu
|
|
257
|
+
<CopyPageMenu
|
|
258
|
+
path={view.pathname}
|
|
259
|
+
origin={config.url ?? ''}
|
|
260
|
+
title={config.title}
|
|
261
|
+
mcp={config.mcp}
|
|
262
|
+
/>
|
|
257
263
|
{/if}
|
|
258
264
|
</div>
|
|
259
265
|
</div>
|
|
@@ -40,6 +40,7 @@ type $$ComponentProps = {
|
|
|
40
40
|
* Show the "Copy page" split button on doc pages: copy the page as
|
|
41
41
|
* Markdown, view the raw `.md`, or open it in ChatGPT / Claude. Requires a
|
|
42
42
|
* catch-all `<path>.md` endpoint over the `svelte-docsmith/llms` index.
|
|
43
|
+
* With `config.mcp` set, the menu also offers "Connect to your editor".
|
|
43
44
|
*/
|
|
44
45
|
copyPage?: boolean;
|
|
45
46
|
/**
|
package/dist/core/config.d.ts
CHANGED
|
@@ -55,6 +55,15 @@ export type DocsmithConfig = {
|
|
|
55
55
|
* page's source path. Omit to hide the edit link.
|
|
56
56
|
*/
|
|
57
57
|
editUrl?: string;
|
|
58
|
+
/**
|
|
59
|
+
* Path of the site's MCP server, e.g. `/mcp` (or an absolute URL). When set,
|
|
60
|
+
* the copy-page menu offers "Connect to your editor" with the server's URL
|
|
61
|
+
* and setup for Claude Code, Cursor and VS Code. The route itself is yours to
|
|
62
|
+
* add, with `mcpHandler`.
|
|
63
|
+
*
|
|
64
|
+
* @experimental Outside the 1.0 stability promise. May change in a minor.
|
|
65
|
+
*/
|
|
66
|
+
mcp?: string;
|
|
58
67
|
/** Optional GitHub URL; renders a link in the header when set. */
|
|
59
68
|
github?: string;
|
|
60
69
|
/** Optional version string, shown in the header (e.g. your library version). */
|
package/dist/core/config.js
CHANGED
|
@@ -17,7 +17,8 @@ export function defineConfig(config) {
|
|
|
17
17
|
'description',
|
|
18
18
|
'url',
|
|
19
19
|
'ogImage',
|
|
20
|
-
'editUrl'
|
|
20
|
+
'editUrl',
|
|
21
|
+
'mcp'
|
|
21
22
|
]) {
|
|
22
23
|
if (config[key] !== undefined && typeof config[key] !== 'string') {
|
|
23
24
|
throw new Error(`[svelte-docsmith] config.${key} must be a string when set.`);
|
|
@@ -37,3 +37,8 @@ export interface InheritedAttributes {
|
|
|
37
37
|
kind: 'element' | 'type';
|
|
38
38
|
label: string;
|
|
39
39
|
}
|
|
40
|
+
/**
|
|
41
|
+
* A generated props table's caption when the author gives no `title`: the
|
|
42
|
+
* component's name, with its type parameters for a generic (`Select<T, U>`).
|
|
43
|
+
*/
|
|
44
|
+
export declare function propsCaption(props: ExtractedProps): string;
|
|
@@ -1 +1,8 @@
|
|
|
1
|
-
|
|
1
|
+
/**
|
|
2
|
+
* A generated props table's caption when the author gives no `title`: the
|
|
3
|
+
* component's name, with its type parameters for a generic (`Select<T, U>`).
|
|
4
|
+
*/
|
|
5
|
+
export function propsCaption(props) {
|
|
6
|
+
const params = props.typeParameters;
|
|
7
|
+
return props.name + (params.length ? `<${params.join(', ')}>` : '');
|
|
8
|
+
}
|
package/dist/core/version.d.ts
CHANGED
|
@@ -127,9 +127,11 @@ export declare function currentOnly<T extends {
|
|
|
127
127
|
/**
|
|
128
128
|
* Content scoped to one version. With no version id (unversioned site) the
|
|
129
129
|
* content passes through unchanged, so every caller stays a no-op off the
|
|
130
|
-
* versioned path.
|
|
130
|
+
* versioned path. Works over any record carrying `version`.
|
|
131
131
|
*/
|
|
132
|
-
export declare function scopeContent
|
|
132
|
+
export declare function scopeContent<T extends {
|
|
133
|
+
version?: string;
|
|
134
|
+
}>(content: T[], versionId: string | undefined): T[];
|
|
133
135
|
/**
|
|
134
136
|
* Map the current page to its equivalent under `to`: swap the version base, and
|
|
135
137
|
* fall back to the target's landing page when that doc doesn't exist there.
|
package/dist/core/version.js
CHANGED
|
@@ -164,7 +164,7 @@ export function currentOnly(items, versions) {
|
|
|
164
164
|
/**
|
|
165
165
|
* Content scoped to one version. With no version id (unversioned site) the
|
|
166
166
|
* content passes through unchanged, so every caller stays a no-op off the
|
|
167
|
-
* versioned path.
|
|
167
|
+
* versioned path. Works over any record carrying `version`.
|
|
168
168
|
*/
|
|
169
169
|
export function scopeContent(content, versionId) {
|
|
170
170
|
if (!versionId)
|
package/dist/generate/llms.d.ts
CHANGED
|
@@ -8,7 +8,22 @@ export type LlmsSite = {
|
|
|
8
8
|
* Without it the links stay site-relative.
|
|
9
9
|
*/
|
|
10
10
|
origin?: string;
|
|
11
|
+
/**
|
|
12
|
+
* The site's MCP server: its path, such as `/mcp`, or an absolute URL. When
|
|
13
|
+
* set, llms.txt tells agents where to connect.
|
|
14
|
+
*
|
|
15
|
+
* @experimental Outside the 1.0 stability promise. May change in a minor.
|
|
16
|
+
*/
|
|
17
|
+
mcp?: string;
|
|
11
18
|
};
|
|
19
|
+
/**
|
|
20
|
+
* Group docs by section and put both the sections and the docs within them in
|
|
21
|
+
* sidebar reading order: items by their `order`, sections by the smallest
|
|
22
|
+
* `order` they contain. Mirrors `navFromContent` so the LLM index matches the
|
|
23
|
+
* on-page navigation instead of falling back to path-alphabetical order. The MCP
|
|
24
|
+
* server's `list_pages` uses it too, so every agent surface agrees on the order.
|
|
25
|
+
*/
|
|
26
|
+
export declare function bySection(docs: LlmsDoc[]): Array<[string, LlmsDoc[]]>;
|
|
12
27
|
/**
|
|
13
28
|
* Build an [llms.txt](https://llmstxt.org) index: the site title and
|
|
14
29
|
* description, then a sectioned list of links to each page. Wire it into a
|
package/dist/generate/llms.js
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
|
+
import { mcpUrl } from '../mcp/connect.js';
|
|
1
2
|
import { join } from '../utils/url.js';
|
|
2
3
|
/**
|
|
3
4
|
* Group docs by section and put both the sections and the docs within them in
|
|
4
5
|
* sidebar reading order: items by their `order`, sections by the smallest
|
|
5
6
|
* `order` they contain. Mirrors `navFromContent` so the LLM index matches the
|
|
6
|
-
* on-page navigation instead of falling back to path-alphabetical order.
|
|
7
|
+
* on-page navigation instead of falling back to path-alphabetical order. The MCP
|
|
8
|
+
* server's `list_pages` uses it too, so every agent surface agrees on the order.
|
|
7
9
|
*/
|
|
8
|
-
function bySection(docs) {
|
|
10
|
+
export function bySection(docs) {
|
|
9
11
|
const groups = new Map();
|
|
10
12
|
for (const doc of docs) {
|
|
11
13
|
const section = doc.section ?? 'Docs';
|
|
@@ -43,6 +45,8 @@ export function generateLlmsTxt(site, docs) {
|
|
|
43
45
|
const out = [`# ${site.title}`];
|
|
44
46
|
if (site.description)
|
|
45
47
|
out.push('', `> ${site.description}`);
|
|
48
|
+
if (site.mcp)
|
|
49
|
+
out.push('', `MCP server: ${mcpUrl(site.mcp, origin)}`);
|
|
46
50
|
for (const [section, items] of bySection(docs)) {
|
|
47
51
|
out.push('', `## ${section}`, '');
|
|
48
52
|
for (const doc of items) {
|
package/dist/index.d.ts
CHANGED
|
@@ -32,3 +32,4 @@ export { generateLlmsTxt, generateLlmsFullTxt, type LlmsSite } from './generate/
|
|
|
32
32
|
export { default as Changelog } from './components/changelog/changelog.svelte';
|
|
33
33
|
export type { ChangelogRelease, ChangelogGroup } from './core/changelog.js';
|
|
34
34
|
export { generateFeed, type FeedSite } from './generate/feed.js';
|
|
35
|
+
export { mcpHandler, type McpOptions } from './mcp/handler.js';
|
package/dist/index.js
CHANGED
|
@@ -49,3 +49,8 @@ export { generateLlmsTxt, generateLlmsFullTxt } from './generate/llms.js';
|
|
|
49
49
|
// Changelog (the generated `svelte-docsmith/changelog` index, plus its feed)
|
|
50
50
|
export { default as Changelog } from './components/changelog/changelog.svelte';
|
|
51
51
|
export { generateFeed } from './generate/feed.js';
|
|
52
|
+
// MCP server (experimental — outside the 1.0 stability promise). Wire it into
|
|
53
|
+
// `src/routes/mcp/+server.ts` over the generated `svelte-docsmith/llms`,
|
|
54
|
+
// `/search` and `/content` indexes, with `prerender = false`: it needs a server
|
|
55
|
+
// runtime.
|
|
56
|
+
export { mcpHandler } from './mcp/handler.js';
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** One editor's setup: where it goes and what to paste. */
|
|
2
|
+
export type EditorSetup = {
|
|
3
|
+
/** The editor's name, e.g. `Cursor`. */
|
|
4
|
+
editor: string;
|
|
5
|
+
/** The config file the snippet belongs in; absent for a shell command. */
|
|
6
|
+
file?: string;
|
|
7
|
+
/** What to paste: a shell command or the file's JSON. */
|
|
8
|
+
code: string;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* The server's absolute URL from the configured `mcp` value: an absolute URL
|
|
12
|
+
* is kept as given, a path is joined to the origin. Without an origin the path
|
|
13
|
+
* stays site-relative, as other links do.
|
|
14
|
+
*/
|
|
15
|
+
export declare function mcpUrl(mcp: string, origin: string): string;
|
|
16
|
+
/** Setup for Claude Code, Cursor and VS Code, for a server at `url`. */
|
|
17
|
+
export declare function editorSetups(title: string, url: string): EditorSetup[];
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How a reader connects their editor to the MCP server: its absolute URL and
|
|
3
|
+
* the setup for each editor we document. One place, so the server's own
|
|
4
|
+
* browser note, the copy-page menu and llms.txt all say the same thing.
|
|
5
|
+
*
|
|
6
|
+
* Pure string work, safe to import from components.
|
|
7
|
+
*/
|
|
8
|
+
import { join } from '../utils/url.js';
|
|
9
|
+
/**
|
|
10
|
+
* The server's absolute URL from the configured `mcp` value: an absolute URL
|
|
11
|
+
* is kept as given, a path is joined to the origin. Without an origin the path
|
|
12
|
+
* stays site-relative, as other links do.
|
|
13
|
+
*/
|
|
14
|
+
export function mcpUrl(mcp, origin) {
|
|
15
|
+
return /^https?:\/\//i.test(mcp) ? mcp : join(origin, mcp);
|
|
16
|
+
}
|
|
17
|
+
/** The name editors list the server under: the site title as a slug. */
|
|
18
|
+
function serverName(title) {
|
|
19
|
+
return (title
|
|
20
|
+
.toLowerCase()
|
|
21
|
+
.replace(/[^a-z\d]+/g, '-')
|
|
22
|
+
.replace(/^-|-$/g, '') || 'docs');
|
|
23
|
+
}
|
|
24
|
+
/** Setup for Claude Code, Cursor and VS Code, for a server at `url`. */
|
|
25
|
+
export function editorSetups(title, url) {
|
|
26
|
+
const name = serverName(title);
|
|
27
|
+
return [
|
|
28
|
+
{ editor: 'Claude Code', code: `claude mcp add --transport http ${name} ${url}` },
|
|
29
|
+
{
|
|
30
|
+
editor: 'Cursor',
|
|
31
|
+
file: '~/.cursor/mcp.json',
|
|
32
|
+
code: JSON.stringify({ mcpServers: { [name]: { url } } }, null, 2)
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
editor: 'VS Code',
|
|
36
|
+
file: '.vscode/mcp.json',
|
|
37
|
+
code: JSON.stringify({ servers: { [name]: { type: 'http', url } } }, null, 2)
|
|
38
|
+
}
|
|
39
|
+
];
|
|
40
|
+
}
|