create-cantip 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sedokina
+
+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,19 @@
+# create-cantip
+
+Scaffold a new [cantip](https://www.npmjs.com/package/cantip) documentation site.
+
+```sh
+npm create cantip my-docs
+cd my-docs
+npm install
+npm run dev
+```
+
+This generates a minimal starter: `docs.config.ts`, a `docs/` folder with a
+sample page, default `public/` assets, and a `package.json` wired to `cantip`.
+
+Then edit `docs.config.ts` to configure your site and drop markdown into `docs/`.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * `create-cantip` — scaffold a new cantip docs site.
+ *
+ *   npm create cantip my-docs
+ *   npm create cantip            # prompts/defaults to ./my-docs
+ *
+ * Copies the `template/` directory into the target, renaming `_package.json` →
+ * `package.json` and `_gitignore` → `.gitignore`, and substituting the project
+ * name + cantip version. Refuses to overwrite a non-empty target.
+ */
+import { fileURLToPath } from 'node:url'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = path.join(HERE, 'template')
+
+/** cantip version to depend on — mirror create-cantip's own version. */
+function cantipVersion() {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(HERE, 'package.json'), 'utf8'))
+		// Pin to the same major.minor line so a fresh scaffold matches this CLI.
+		return `^${pkg.version}`
+	} catch {
+		return 'latest'
+	}
+}
+
+/** Files that need their leading underscore stripped (npm strips dotfiles from publishes). */
+const RENAME = new Map([
+	['_package.json', 'package.json'],
+	['_gitignore', '.gitignore'],
+])
+
+/** Apply name/version substitutions to text files. */
+function substitute(content, projectName) {
+	return content
+		.replaceAll('__PROJECT_NAME__', projectName)
+		.replaceAll('__CANTIP_VERSION__', cantipVersion())
+}
+
+/** Files we run substitution on (others are copied verbatim — e.g. SVGs). */
+const SUBSTITUTE_EXT = new Set(['.json', '.md', '.ts', '.tsx', ''])
+
+function copyDir(srcDir, destDir, projectName) {
+	fs.mkdirSync(destDir, { recursive: true })
+	for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+		const srcPath = path.join(srcDir, entry.name)
+		const outName = RENAME.get(entry.name) ?? entry.name
+		const destPath = path.join(destDir, outName)
+		if (entry.isDirectory()) {
+			copyDir(srcPath, destPath, projectName)
+		} else if (SUBSTITUTE_EXT.has(path.extname(entry.name))) {
+			fs.writeFileSync(destPath, substitute(fs.readFileSync(srcPath, 'utf8'), projectName))
+		} else {
+			fs.copyFileSync(srcPath, destPath)
+		}
+	}
+}
+
+function main() {
+	const targetArg = process.argv[2] || 'my-docs'
+	const targetDir = path.resolve(process.cwd(), targetArg)
+	const projectName = path.basename(targetDir)
+
+	if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
+		console.error(`✖ Target directory "${targetArg}" exists and is not empty. Aborting.`)
+		process.exit(1)
+	}
+
+	console.log(`▶ Scaffolding a cantip docs site in ${targetDir}…`)
+	copyDir(TEMPLATE_DIR, targetDir, projectName)
+
+	console.log(
+		`\n✔ Done. Next steps:\n\n` +
+			`  cd ${targetArg}\n` +
+			`  npm install\n` +
+			`  npm run dev\n\n` +
+			`Edit docs.config.ts to configure your site, and drop markdown into content/.\n`,
+	)
+}
+
+main()

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "create-cantip",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Scaffold a new cantip documentation site (`npm create cantip my-docs`).",
+  "keywords": [
+    "cantip",
+    "documentation",
+    "docs",
+    "scaffold",
+    "create",
+    "starter"
+  ],
+  "license": "MIT",
+  "author": "Sedokina",
+  "homepage": "https://github.com/Sedokina/cantip/tree/main/packages/create-cantip#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sedokina/cantip.git",
+    "directory": "packages/create-cantip"
+  },
+  "bugs": {
+    "url": "https://github.com/Sedokina/cantip/issues"
+  },
+  "bin": {
+    "create-cantip": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/README.md

@@ -0,0 +1,34 @@
+# __PROJECT_NAME__
+
+A documentation site built with [cantip](https://www.npmjs.com/package/cantip).
+
+## Develop
+
+```sh
+npm install
+npm run dev        # generate content + start the dev server
+```
+
+## Build & serve
+
+```sh
+npm run build      # generate + production build
+npm run start      # serve the build
+```
+
+## Add content
+
+- Drop `.md` files into `docs/` — each becomes a page at its file path.
+- Or edit `docs.config.ts` to add `projects`, each pointing `source` at a folder,
+  a git submodule, or any path.
+
+## Customize
+
+Everything lives in `docs.config.ts`:
+
+- **Branding** — `site.title`, `site.logo`, `site.favicon`, `site.defaultTheme`.
+- **Theme** — `theme.colors` (OKLCH tokens), no CSS editing required.
+- **Components** — `components` maps `Home`/`DocPage`/`TopBar`/`Toc` to your own
+  `.tsx` files.
+
+See the cantip docs for the full config reference.

package/template/_gitignore

@@ -0,0 +1,17 @@
+# dependencies
+node_modules/
+
+# build output
+build/
+.cache/
+
+# generated by `cantip generate` (regenerated each build)
+content/
+app/generated/
+public/pagefind/
+
+# logs
+npm-debug.log*
+
+# os
+.DS_Store

package/template/_package.json

@@ -0,0 +1,16 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "scripts": {
+    "generate": "cantip generate",
+    "dev": "cantip dev",
+    "build": "cantip build",
+    "start": "cantip start",
+    "typecheck": "cantip typecheck"
+  },
+  "dependencies": {
+    "cantip": "__CANTIP_VERSION__"
+  }
+}

package/template/docs/intro.md

@@ -0,0 +1,25 @@
+---
+title: Welcome
+---
+
+# Welcome to your docs
+
+This page lives at `docs/intro.md` and is served at **`/intro/`**.
+
+Drop more `.md` files into `docs/` — each becomes a page at its file path.
+Folders become sections in the sidebar.
+
+## What you can write
+
+Standard Markdown, plus:
+
+- **Wikilinks** — `[[another-page]]` to link between docs.
+- **Callouts** — Obsidian-style `> [!note]` blocks.
+- **Math** — `$inline$` and `$$block$$` via KaTeX.
+- **Tables, code blocks, task lists** — full GitHub-Flavored Markdown.
+
+## Next steps
+
+1. Edit `docs.config.ts` to set your title, theme, and content sources.
+2. Run `npx cantip dev` and open the printed URL.
+3. Add pages, or point a project `source` at a git submodule / existing folder.

package/template/docs.config.ts

@@ -0,0 +1,46 @@
+import { defineConfig } from 'cantip/config'
+
+/**
+ * Your docs site config. Every field is optional — start minimal and add as you
+ * grow. Run `npx cantip dev` after editing.
+ *
+ * Content sources: each `project` points `source` at a directory of markdown
+ * (a loose folder, a git submodule, or any path). The project `id` becomes the
+ * first URL segment. Or drop loose files into ./content and enable `general`
+ * below to serve them at the root with no project concept at all.
+ */
+export default defineConfig({
+	site: {
+		title: 'My Docs',
+		description: 'Documentation built with cantip.',
+		// Drives sort order + search tokenisation. e.g. 'en', 'ru', 'de'.
+		lang: 'en',
+		defaultTheme: 'dark', // 'dark' | 'light'
+	},
+
+	// The no-project bucket: loose markdown in ./docs, served at the root
+	// (e.g. docs/intro.md → /intro/). Remove this and use `projects` instead if
+	// you want multiple named docsets with a project switcher. (Note: keep your
+	// source dir distinct from ./content — that name is the generated output.)
+	general: {
+		enabled: true,
+		source: './docs',
+	},
+
+	// Named projects (uncomment to use instead of / alongside `general`):
+	// projects: [
+	//   {
+	//     id: 'guide',
+	//     name: 'User Guide',
+	//     source: './content/guide',   // loose folder, submodule, or any path
+	//     description: 'How to use the product.',
+	//     canvas: false,               // set true to ingest .canvas files too
+	//   },
+	// ],
+
+	// Override the brand color (and any other OKLCH token) without touching CSS:
+	// theme: { colors: { dark: { '--brand': 'oklch(0.7 0.2 250)' } } },
+
+	// Swap any built-in component for your own (Home, DocPage, TopBar, Toc):
+	// components: { Home: './app/MyHome.tsx' },
+})

package/template/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="7" fill="#4C3FB0"/><path d="M9 23V9h3v6l5-6h3.6l-5.2 6.2L24 23h-3.8l-4.2-5.6L12 19.8V23H9Z" fill="#fff"/></svg>

package/template/public/logo-dark.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 24" height="24"><rect width="24" height="24" rx="6" fill="#7c6ff0"/><path d="M7 18V6h2.4v4.8L13 6h2.9l-4.2 5L16 18h-3l-3.3-4.5L9.4 15.4V18H7Z" fill="#fff"/><text x="32" y="17" font-family="system-ui,sans-serif" font-size="14" font-weight="600" fill="#f5f5f5">My Docs</text></svg>

package/template/public/logo-light.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 24" height="24"><rect width="24" height="24" rx="6" fill="#4C3FB0"/><path d="M7 18V6h2.4v4.8L13 6h2.9l-4.2 5L16 18h-3l-3.3-4.5L9.4 15.4V18H7Z" fill="#fff"/><text x="32" y="17" font-family="system-ui,sans-serif" font-size="14" font-weight="600" fill="#1a1a1a">My Docs</text></svg>