create-svelte-docsmith 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 George Daskalakis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# create-svelte-docsmith
+
+Scaffold a documentation site powered by [Svelte DocSmith](https://www.npmjs.com/package/svelte-docsmith).
+
+```bash
+npm create svelte-docsmith@latest my-docs
+```
+
+```bash
+pnpm create svelte-docsmith my-docs
+```
+
+```bash
+yarn create svelte-docsmith my-docs
+```
+
+You can also run it without a name and answer the prompts:
+
+```bash
+npm create svelte-docsmith@latest
+```
+
+It asks a short set of questions (all with sensible defaults):
+
+- **Directory** — where to create the project (skipped if you passed a name).
+- **Site title** — used in the header and `site-config.ts`.
+- **Theme** — a built-in preset, or the default.
+- **Install dependencies?** — runs your package manager for you.
+- **Initialize a git repository?**
+
+Then it writes a ready-to-run SvelteKit + Tailwind v4 project wired with
+DocSmith: the markdown pipeline, the Vite plugin, the style contract, a
+`DocsShell` layout, a 404 page, and two sample doc pages.
+
+```bash
+cd my-docs
+npm run dev
+```
+
+Add markdown files under `src/routes/docs/` and they appear in the sidebar,
+styled, highlighted, and searchable.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync } from 'node:child_process';
+import * as p from '@clack/prompts';
+
+const templateDir = fileURLToPath(new URL('./template', import.meta.url));
+
+const PRESETS = [
+	{ value: 'default', label: 'Default (Tangerine)' },
+	{ value: 'darkmatter', label: 'Darkmatter' },
+	{ value: 'amethyst', label: 'Amethyst' },
+	{ value: 'graphite', label: 'Graphite' },
+	{ value: 'evergreen', label: 'Evergreen' },
+	{ value: 'rose', label: 'Rose' },
+	{ value: 'ocean', label: 'Ocean' },
+	{ value: 'nord', label: 'Nord' },
+	{ value: 'claude', label: 'Claude' },
+	{ value: 'bubblegum', label: 'Bubblegum' },
+	{ value: 'mono', label: 'Mono' }
+];
+
+/** Copy `src` into `dest`, renaming the packaged `_gitignore` back to `.gitignore`. */
+function copyTemplate(src, dest) {
+	fs.mkdirSync(dest, { recursive: true });
+	for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+		const from = path.join(src, entry.name);
+		const name = entry.name === '_gitignore' ? '.gitignore' : entry.name;
+		const to = path.join(dest, name);
+		if (entry.isDirectory()) copyTemplate(from, to);
+		else fs.copyFileSync(from, to);
+	}
+}
+
+/** Detect the package manager that invoked us (npm/pnpm/yarn/bun). */
+function detectPackageManager() {
+	const ua = process.env.npm_config_user_agent ?? '';
+	if (ua.startsWith('pnpm')) return 'pnpm';
+	if (ua.startsWith('yarn')) return 'yarn';
+	if (ua.startsWith('bun')) return 'bun';
+	return 'npm';
+}
+
+function toPackageName(dir) {
+	return (
+		path
+			.basename(path.resolve(dir))
+			.toLowerCase()
+			.replace(/[^a-z0-9-~]/g, '-')
+			.replace(/^-+|-+$/g, '') || 'my-docs'
+	);
+}
+
+function toTitle(name) {
+	return (
+		name
+			.split(/[-_\s]+/)
+			.filter(Boolean)
+			.map((w) => w[0].toUpperCase() + w.slice(1))
+			.join(' ') || 'My Docs'
+	);
+}
+
+/** Fill the template placeholders, and wire the chosen theme preset into app.css. */
+function applyOptions(dest, { pkgName, title, preset }) {
+	const edit = (rel, fn) => {
+		const file = path.join(dest, rel);
+		fs.writeFileSync(file, fn(fs.readFileSync(file, 'utf-8')));
+	};
+	edit('package.json', (t) => t.replaceAll('{{PROJECT_NAME}}', pkgName));
+	edit('README.md', (t) => t.replaceAll('{{PROJECT_NAME}}', title));
+	edit('src/lib/site-config.ts', (t) => t.replaceAll('{{SITE_TITLE}}', title));
+	if (preset && preset !== 'default') {
+		edit('src/app.css', (t) =>
+			t.replace(
+				"@import 'svelte-docsmith/theme.css';\n",
+				`@import 'svelte-docsmith/theme.css';\n@import 'svelte-docsmith/themes/${preset}.css';\n`
+			)
+		);
+	}
+}
+
+/** Run a command asynchronously so the event loop stays free (a synchronous
+ *  child would freeze the spinner animation). Resolves with the exit code. */
+function run(cmd, args, cwd) {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, {
+			cwd,
+			stdio: 'ignore',
+			shell: process.platform === 'win32'
+		});
+		child.on('close', (code) => resolve(code ?? 1));
+		child.on('error', () => resolve(1));
+	});
+}
+
+/** Exit gracefully when the user hits Ctrl+C at a prompt. */
+function unlessCancelled(value) {
+	if (p.isCancel(value)) {
+		p.cancel('Cancelled.');
+		process.exit(0);
+	}
+	return value;
+}
+
+async function main() {
+	p.intro('create-svelte-docsmith');
+	const interactive = Boolean(process.stdin.isTTY);
+	const pm = detectPackageManager();
+
+	// 1. Target directory (skip the prompt if passed as an argument).
+	let target = process.argv[2];
+	if (!target) {
+		target = interactive
+			? unlessCancelled(
+					await p.text({
+						message: 'Where should we create your docs?',
+						placeholder: './my-docs',
+						defaultValue: './my-docs'
+					})
+				)
+			: './my-docs';
+	}
+	const dest = path.resolve(process.cwd(), target);
+	const rel = path.relative(process.cwd(), dest) || '.';
+
+	// 2. Refuse to clobber a non-empty directory (unless the user confirms).
+	if (fs.existsSync(dest) && fs.readdirSync(dest).length > 0) {
+		const overwrite = interactive
+			? unlessCancelled(
+					await p.confirm({
+						message: `${rel} is not empty. Create the site here anyway?`,
+						initialValue: false
+					})
+				)
+			: false;
+		if (!overwrite) {
+			p.cancel(`${rel} is not empty. Aborting.`);
+			process.exit(1);
+		}
+	}
+
+	const defaultTitle = toTitle(toPackageName(dest));
+
+	// 3. Site title.
+	const title = interactive
+		? unlessCancelled(
+				await p.text({
+					message: 'Site title',
+					placeholder: defaultTitle,
+					defaultValue: defaultTitle
+				})
+			) || defaultTitle
+		: defaultTitle;
+
+	// 4. Theme preset.
+	const preset = interactive
+		? unlessCancelled(
+				await p.select({ message: 'Theme', options: PRESETS, initialValue: 'default' })
+			)
+		: 'default';
+
+	// 5 & 6. Install dependencies / init git.
+	const doInstall = interactive
+		? unlessCancelled(
+				await p.confirm({ message: `Install dependencies with ${pm}?`, initialValue: true })
+			)
+		: false;
+	const doGit = interactive
+		? unlessCancelled(
+				await p.confirm({ message: 'Initialize a git repository?', initialValue: true })
+			)
+		: false;
+
+	// Scaffold.
+	copyTemplate(templateDir, dest);
+	applyOptions(dest, { pkgName: toPackageName(dest), title, preset });
+
+	if (doInstall) {
+		const s = p.spinner();
+		s.start(`Installing dependencies with ${pm} (this can take a minute)`);
+		const code = await run(pm, ['install'], dest);
+		if (code === 0) s.stop('Dependencies installed');
+		else s.stop(`Could not install with ${pm}; run it yourself later`);
+	}
+
+	if (doGit) {
+		// Fast and non-interactive, so a synchronous call is fine here.
+		spawnSync('git', ['init', '-q'], { cwd: dest, stdio: 'ignore' });
+	}
+
+	// Next steps.
+	const runCmd = pm === 'npm' ? 'npm run' : pm;
+	const steps = [];
+	if (rel !== '.') steps.push(`cd ${rel}`);
+	if (!doInstall) steps.push(`${pm} install`);
+	steps.push(`${runCmd} dev`);
+	p.note(steps.join('\n'), 'Next steps');
+	p.outro('Add markdown under src/routes/docs/ and it appears in the sidebar.');
+}
+
+main().catch((err) => {
+	console.error(err instanceof Error ? err.message : err);
+	process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-svelte-docsmith",
+  "version": "0.1.0",
+  "description": "Scaffold a documentation site powered by Svelte DocSmith.",
+  "type": "module",
+  "bin": {
+    "create-svelte-docsmith": "index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "documentation",
+    "docs",
+    "create",
+    "scaffold",
+    "svelte-docsmith"
+  ],
+  "author": {
+    "name": "George Daskalakis",
+    "email": "george.dask97@gmail.com",
+    "url": "https://github.com/geodask"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geodask/svelte-docsmith.git",
+    "directory": "packages/create-svelte-docsmith"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  }
+}

package/template/README.md

@@ -0,0 +1,41 @@
+# {{PROJECT_NAME}}
+
+A documentation site built with [Svelte DocSmith](https://docsmith.geodask.com).
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+## Write docs
+
+Add a `+page.md` file under `src/routes/docs/`. Its frontmatter drives the
+sidebar:
+
+```md
+---
+title: My Page
+section: Guides
+order: 1
+---
+
+## Hello
+
+Your content here.
+```
+
+Save it and the page appears in the sidebar, styled and highlighted.
+
+## Configure
+
+- **Site title, nav, footer, SEO** — `src/lib/site-config.ts`
+- **Theme** — `src/app.css` (import a preset, or override tokens)
+
+## Build
+
+```bash
+npm run build
+npm run preview
+```

package/template/_gitignore

@@ -0,0 +1,21 @@
+node_modules
+
+# Output
+.output
+.vercel
+.netlify
+.wrangler
+/.svelte-kit
+/build
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/*
+!.vscode/extensions.json
+.idea
+
+# Env
+.env
+.env.*
+!.env.example

package/template/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "{{PROJECT_NAME}}",
+	"version": "0.0.0",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev",
+		"build": "vite build",
+		"preview": "vite preview",
+		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json"
+	},
+	"dependencies": {
+		"svelte-docsmith": "^0.3.0"
+	},
+	"devDependencies": {
+		"@sveltejs/adapter-auto": "^7.0.1",
+		"@sveltejs/kit": "^2.16.0",
+		"@sveltejs/vite-plugin-svelte": "^7.1.2",
+		"@tailwindcss/vite": "^4.0.0",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
+		"tailwindcss": "^4.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^8.0.0"
+	}
+}

package/template/src/app.css

@@ -0,0 +1,11 @@
+@import 'tailwindcss';
+
+/* The whole Svelte DocSmith style contract in one import: it makes Tailwind scan
+ * the package, registers the design tokens for light and dark, and pulls in the
+ * typography and animation plugins. */
+@import 'svelte-docsmith/theme.css';
+
+/* Prefer a different look? Import a preset after theme.css and it wins:
+ *   @import 'svelte-docsmith/themes/darkmatter.css';
+ * Available: darkmatter, tangerine, amethyst, graphite, evergreen, rose, ocean,
+ * nord, claude, bubblegum, mono. Or override individual tokens yourself. */

package/template/src/app.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		%sveltekit.head%
+	</head>
+	<body data-sveltekit-preload-data="hover">
+		<div style="display: contents">%sveltekit.body%</div>
+	</body>
+</html>

package/template/src/lib/site-config.ts

@@ -0,0 +1,14 @@
+import type { DocsmithConfig } from 'svelte-docsmith';
+
+// The whole-site config passed to DocsShell. Set your title, links, and the
+// SEO/social defaults here. See https://docsmith.geodask.com.
+export const siteConfig: DocsmithConfig = {
+	title: '{{SITE_TITLE}}',
+	// github: 'https://github.com/you/your-library',
+	// description: 'A short tagline, used as the default meta description.',
+	// url: 'https://your-docs.dev',
+	nav: [{ label: 'Docs', href: '/docs/introduction' }],
+	footer: {
+		copyright: `© ${new Date().getFullYear()} {{SITE_TITLE}}`
+	}
+};

package/template/src/routes/+error.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+	import { docs } from 'svelte-docsmith/content';
+	import { ErrorPage } from 'svelte-docsmith';
+	import { siteConfig } from '$lib/site-config';
+</script>
+
+<ErrorPage
+	config={siteConfig}
+	content={docs}
+	search={() => import('svelte-docsmith/search').then((m) => m.docs)}
+	home="/docs/introduction"
+	homeLabel="Back to the docs"
+/>

package/template/src/routes/+layout.svelte

@@ -0,0 +1,8 @@
+<script lang="ts">
+	import '../app.css';
+	import type { Snippet } from 'svelte';
+
+	const { children }: { children: Snippet } = $props();
+</script>
+
+{@render children()}

package/template/src/routes/+page.ts

@@ -0,0 +1,7 @@
+import { redirect } from '@sveltejs/kit';
+
+// Send the site root to the first docs page. Replace this file with a
+// `+page.svelte` if you'd rather have a custom landing page.
+export function load() {
+	redirect(307, '/docs/introduction');
+}

package/template/src/routes/docs/+layout.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import { docs } from 'svelte-docsmith/content';
+	import { DocsShell } from 'svelte-docsmith';
+	import { siteConfig } from '$lib/site-config';
+	import type { Snippet } from 'svelte';
+
+	const { children }: { children: Snippet } = $props();
+</script>
+
+<DocsShell
+	config={siteConfig}
+	content={docs}
+	search={() => import('svelte-docsmith/search').then((m) => m.docs)}
+	pattern
+>
+	{@render children()}
+</DocsShell>

package/template/src/routes/docs/introduction/+page.md

@@ -0,0 +1,32 @@
+---
+title: Introduction
+description: Welcome to your new documentation site.
+section: Getting Started
+order: 1
+---
+
+<script>
+	import { Callout } from 'svelte-docsmith';
+</script>
+
+Welcome to your new documentation site, built with Svelte DocSmith.
+
+## How it works
+
+Every `+page.md` file under `src/routes/docs/` becomes a page, and its
+frontmatter drives the sidebar:
+
+- `title` names the page and its sidebar entry.
+- `section` groups pages in the sidebar.
+- `order` sorts pages within a group.
+
+<Callout variant="tip" title="Try it">
+
+Open `src/routes/docs/introduction/+page.md`, edit this text, and save. The page
+updates instantly.
+
+</Callout>
+
+## Next
+
+Head to the [Quick Start](/docs/quick-start) for the authoring basics.

package/template/src/routes/docs/quick-start/+page.md

@@ -0,0 +1,26 @@
+---
+title: Quick Start
+description: Write your first pages.
+section: Getting Started
+order: 2
+---
+
+Add a markdown file anywhere under `src/routes/docs/` and it shows up in the
+sidebar, styled and highlighted.
+
+## Code blocks
+
+Fenced code is highlighted by Shiki. Emphasize a line with a comment marker:
+
+```ts
+const docs = loadDocs();
+const active = docs.find((d) => d.current); // [!code highlight]
+```
+
+## Components
+
+DocSmith ships components you can use right inside markdown: callouts, tabs,
+cards, steps, and more. Import them in a `<script>` block at the top of the page,
+then use them in the body.
+
+Learn more in the [Svelte DocSmith documentation](https://docsmith.geodask.com).

package/template/static/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+	<path d="M12 7v14" />
+	<path d="M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z" />
+</svg>

package/template/svelte.config.js

@@ -0,0 +1,15 @@
+import adapter from '@sveltejs/adapter-auto';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { docsmith } from 'svelte-docsmith/preprocess';
+
+/** @type {import('@sveltejs/kit').Config} */
+const config = {
+	// `.md` files are compiled as routes by the DocSmith preprocessor.
+	extensions: ['.svelte', '.md'],
+	preprocess: [vitePreprocess(), docsmith()],
+	kit: {
+		adapter: adapter()
+	}
+};
+
+export default config;

package/template/tsconfig.json

@@ -0,0 +1,14 @@
+{
+	"extends": "./.svelte-kit/tsconfig.json",
+	"compilerOptions": {
+		"allowJs": true,
+		"checkJs": true,
+		"esModuleInterop": true,
+		"forceConsistentCasingInFileNames": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+		"sourceMap": true,
+		"strict": true,
+		"moduleResolution": "bundler"
+	}
+}

package/template/vite.config.ts

@@ -0,0 +1,10 @@
+import tailwindcss from '@tailwindcss/vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import { docsmith } from 'svelte-docsmith/vite';
+
+export default defineConfig({
+	// `docsmith()` builds the content + search indexes and powers LiveExample.
+	// It must come before sveltekit().
+	plugins: [docsmith(), tailwindcss(), sveltekit()]
+});