notespress 0.1.0 → 0.1.1

package/README.md

@@ -1,42 +1,24 @@
-# blog-vitepress
+# notespress
 
-一个用于托管个人笔记站的 VitePress 外壳仓库，同时也包含一个可发布的 `notespress` CLI。
+`notespress` 是一个把 Markdown 笔记目录直接生成为 VitePress 博客站点的 CLI。
 
-Markdown 内容放在 `myBlog` 子模块中，当前仓库负责：
+它默认把当前目录当作内容目录，自动生成导航、侧边栏和代码片段页面，不要求你手工维护 `.vitepress` 配置。
 
-- 站点配置
-- 自动生成导航
-- 代码示例包装页生成
-- GitHub Pages 部署
-
-## 快速开始
-
-```bash
-git clone <repo-url>
-cd blog-vitepress
-git submodule update --init --recursive
-pnpm install
-pnpm dev
-```
-
-## 作为 npm 包使用
-
-CLI 的目标用法是：在任意 Markdown 笔记目录下直接生成博客站点。
-
-本地安装：
+## 安装
 
 ```bash
 npm install -D notespress
-npx notespress build
 ```
 
-或者直接执行一次性命令：
+一次性运行也可以：
 
 ```bash
 pnpm dlx notespress build
 ```
 
-常用命令：
+## 快速开始
+
+在你的 Markdown 笔记目录里执行：
 
 ```bash
 notespress dev
@@ -44,48 +26,78 @@ notespress build
 notespress preview
 ```
 
-默认行为：
+如果你没有全局安装，可以改用：
+
+```bash
+npx notespress dev
+npx notespress build
+npx notespress preview
+```
+
+## 默认行为
 
 - 当前目录作为内容目录
 - 构建产物输出到 `dist/`
 - 临时工作区输出到 `.blog-cli/`
 - `.js`、`.ts`、`.html` 会自动生成 `snippets/` 页面
+- 不会把 `.vitepress` 配置写回你的笔记目录
 
-## 目录结构
+## 常用命令
 
-- `myBlog/`：Markdown 内容仓库，使用 git submodule 管理
-- `.vitepress/`：VitePress 配置
-- `docs/`：项目说明页
-- `scripts/`：构建前生成代码示例页面
+```bash
+notespress dev [content-dir]
+notespress build [content-dir]
+notespress preview [content-dir]
+notespress prepare-content [content-dir]
+```
 
-## 自动导航
+示例：
 
-站点使用 `vitepress-auto-navigation` 根据 `myBlog` 目录自动生成 `nav` 和 `sidebar`。如果本地还没有拉取子模块，站点仍能启动，但不会显示笔记导航。
+```bash
+notespress build .
+notespress build ./notes --out-dir ./site-dist
+notespress dev ./notes --port 3000
+notespress preview ./notes --port 4173
+```
 
-除了 Markdown 页面，站点还会在构建前扫描 `myBlog` 里的 `.js`、`.ts` 和 `.html` 文件，并自动生成 `snippets/` 下的包装页，让这些代码文件也能通过导航访问。
+## 适用目录
 
-## 从 `myBlog` 直接生成网站
+适合这类目录结构：
 
-根仓库现在提供了一个 `notespress`。如果你进入 `myBlog/`，可以直接运行：
+```text
+notes
+├─ README.md
+├─ frontend
+│  ├─ react.md
+│  └─ vue.md
+└─ code
+   └─ demo.ts
+```
+
+`notespress` 会根据目录结构生成导航，并把代码文件挂到 `/snippets/...` 路由下。
+
+## 高级用法
+
+如果你希望把当前目录初始化成一个长期维护的本地项目，再使用：
 
 ```bash
-pnpm build
-pnpm dev
-pnpm preview
+notespress init
 ```
 
-这些脚本会调用上层仓库里的 `notespress`，临时创建一个独立的 VitePress 工作区，并把当前 `myBlog/` 目录生成为静态站点。
+它会尽量保守地初始化当前目录：
+
+- 创建或合并 `package.json`
+- 写入 `dev`、`build`、`preview` 脚本
+- 添加 `.gitignore` 中的 `node_modules`、`dist`、`.blog-cli`
+- 如果根目录没有 `README.md` 或 `index.md`，创建一个起始首页
+
+如果要覆盖已有脚本或首页，可以加 `--force`。
 
-- 输出目录默认是 `myBlog/dist`
-- 临时工作区在 `myBlog/.blog-cli`
-- 不会把 `.vitepress` 配置写回 `myBlog/`
-- `.js`、`.ts`、`.html` 文件会自动生成 `snippets/` 页面
+## 仓库说明
 
-## 部署
+当前仓库除了发布 `notespress` 包，也保留了一个用于自用和演示的 `blog-vitepress` 站点壳。
 
-`.github/workflows/deploy.yml` 会在 `master` 分支收到 push 后自动：
+仓库结构和本地开发说明放在：
 
-1. 拉取仓库和子模块
-2. 安装依赖
-3. 构建 VitePress 站点
-4. 发布到 GitHub Pages
+- [docs/index.md](/home/dev/workplace/github-repositories/blog-vitepress/docs/index.md)
+- [docs/repository.md](/home/dev/workplace/github-repositories/blog-vitepress/docs/repository.md)

package/bin/blog-cli.mjs

@@ -2,6 +2,7 @@
 
 import { createServer, build, serve } from "vitepress"
 
+import { initNotespressProject } from "../lib/init.mjs"
 import { generateSnippetPages } from "../lib/snippets.mjs"
 import { prepareStandaloneWorkspace, resolveRepositoryRoot } from "../lib/standalone-site.mjs"
 
@@ -13,6 +14,7 @@ Usage:
   notespress dev [content-dir] [--port 5173] [--host 0.0.0.0]
   notespress preview [content-dir] [--port 4173]
   notespress prepare-content [content-dir] [--output-dir dir] [--route-base /myBlog]
+  notespress init [content-dir] [--force]   # optional project setup
 
 Aliases:
   build-site -> build
@@ -83,6 +85,30 @@ async function runPrepareContent(positionals, options) {
   process.stdout.write(`Generated ${result.count} snippet pages in ${result.outputDir}\n`)
 }
 
+async function runInit(positionals, options) {
+  const result = initNotespressProject(resolveContentDir(positionals, options), {
+    force: options.force === true,
+  })
+
+  process.stdout.write(`Initialized notespress in ${result.targetDir}\n`)
+
+  if (result.packageResult.changes.length > 0) {
+    process.stdout.write(`package.json: ${result.packageResult.changes.join(", ")}\n`)
+  }
+
+  if (result.gitignoreResult.additions.length > 0) {
+    process.stdout.write(`.gitignore: added ${result.gitignoreResult.additions.join(", ")}\n`)
+  }
+
+  if (result.readmeResult.created) {
+    process.stdout.write("README.md: created starter page\n")
+  }
+
+  process.stdout.write("\nNext steps:\n")
+  process.stdout.write("  1. Run `npm install` or `pnpm install`\n")
+  process.stdout.write("  2. Run `npx notespress dev` or `pnpm dev`\n")
+}
+
 async function runBuild(positionals, options) {
   const workspace = prepareStandaloneWorkspace({
     contentDir: resolveContentDir(positionals, options),
@@ -144,6 +170,9 @@ async function main() {
   const { command, options, positionals } = parseArgs(process.argv.slice(2))
 
   switch (command) {
+    case "init":
+      await runInit(positionals, options)
+      return
     case "build":
     case "build-site":
       await runBuild(positionals, options)

package/lib/init.mjs

@@ -0,0 +1,162 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const GENERATED_SCRIPTS = {
+  dev: "notespress dev .",
+  build: "notespress build .",
+  preview: "notespress preview .",
+}
+
+const GITIGNORE_ENTRIES = [".blog-cli", "dist", "node_modules"]
+
+function packageRoot() {
+  return resolve(fileURLToPath(new URL("..", import.meta.url)))
+}
+
+function readOwnPackageMeta() {
+  const packageJsonPath = join(packageRoot(), "package.json")
+  return JSON.parse(readFileSync(packageJsonPath, "utf8"))
+}
+
+function ensureDirectory(targetDir) {
+  if (!existsSync(targetDir)) {
+    mkdirSync(targetDir, { recursive: true })
+    return
+  }
+
+  if (!statSync(targetDir).isDirectory()) {
+    throw new Error(`Target is not a directory: ${targetDir}`)
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"))
+}
+
+function writeJson(filePath, value) {
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function upsertPackageJson(targetDir, options) {
+  const packageJsonPath = join(targetDir, "package.json")
+  const ownPackage = readOwnPackageMeta()
+  const force = options.force === true
+  const changes = []
+  let packageJson
+
+  if (existsSync(packageJsonPath)) {
+    packageJson = readJson(packageJsonPath)
+  } else {
+    packageJson = {
+      name: basename(targetDir),
+      private: true,
+    }
+    changes.push("created package.json")
+  }
+
+  if (packageJson.private == null) {
+    packageJson.private = true
+    changes.push("set package.json private=true")
+  }
+
+  packageJson.scripts ??= {}
+
+  for (const [name, command] of Object.entries(GENERATED_SCRIPTS)) {
+    if (packageJson.scripts[name] == null || force) {
+      packageJson.scripts[name] = command
+      changes.push(`set script ${name}`)
+      continue
+    }
+  }
+
+  packageJson.devDependencies ??= {}
+
+  if (packageJson.devDependencies.notespress == null || force) {
+    packageJson.devDependencies.notespress = `^${ownPackage.version}`
+    changes.push(`set devDependency notespress=^${ownPackage.version}`)
+  }
+
+  writeJson(packageJsonPath, packageJson)
+
+  return {
+    packageJsonPath,
+    changes,
+  }
+}
+
+function upsertGitignore(targetDir) {
+  const gitignorePath = join(targetDir, ".gitignore")
+  const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : ""
+  const normalized = existing.replace(/\r\n/g, "\n")
+  const lines = normalized === "" ? [] : normalized.split("\n")
+  const existingEntries = new Set(lines.filter(Boolean))
+  const additions = []
+
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (existingEntries.has(entry)) {
+      continue
+    }
+
+    additions.push(entry)
+    lines.push(entry)
+  }
+
+  const output = `${lines.filter((line, index) => index < lines.length - 1 || line !== "").join("\n")}\n`
+  writeFileSync(gitignorePath, output)
+
+  return {
+    gitignorePath,
+    additions,
+  }
+}
+
+function hasRootIndexPage(targetDir) {
+  return existsSync(join(targetDir, "README.md")) || existsSync(join(targetDir, "index.md"))
+}
+
+function createStarterReadme(targetDir, options) {
+  const readmePath = join(targetDir, "README.md")
+
+  if (hasRootIndexPage(targetDir) && options.force !== true) {
+    return {
+      readmePath,
+      created: false,
+    }
+  }
+
+  const title = basename(targetDir)
+  writeFileSync(
+    readmePath,
+    `# ${title}
+
+Welcome to your notes site.
+
+- Run \`notespress dev\` for local preview
+- Run \`notespress build\` to generate \`dist/\`
+- Put Markdown files into this directory and organize them by folders
+`,
+  )
+
+  return {
+    readmePath,
+    created: true,
+  }
+}
+
+export function initNotespressProject(targetDir, options = {}) {
+  const resolvedDir = resolve(targetDir)
+
+  ensureDirectory(resolvedDir)
+
+  const packageResult = upsertPackageJson(resolvedDir, options)
+  const gitignoreResult = upsertGitignore(resolvedDir)
+  const readmeResult = createStarterReadme(resolvedDir, options)
+
+  return {
+    targetDir: resolvedDir,
+    packageResult,
+    gitignoreResult,
+    readmeResult,
+  }
+}

package/lib/standalone-site.mjs

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto"
-import { mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs"
 import { basename, dirname, join, resolve } from "node:path"
+import { createRequire } from "node:module"
 import { fileURLToPath, pathToFileURL } from "node:url"
 
 import { generateSnippetPages, IGNORED_DIRS } from "./snippets.mjs"
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const require = createRequire(import.meta.url)
 
 function workspaceIdFor(contentDir) {
   const hash = createHash("sha1").update(contentDir).digest("hex").slice(0, 8)
@@ -55,6 +57,30 @@ function mirrorContentEntries(contentDir, workspaceRoot) {
   }
 }
 
+function resolvePackageDir(packageName) {
+  return dirname(require.resolve(`${packageName}/package.json`))
+}
+
+function linkRuntimeDependencies(workspaceRoot) {
+  const nodeModulesDir = join(workspaceRoot, "node_modules")
+
+  ensureDir(nodeModulesDir)
+  symlinkSync(resolvePackageDir("vitepress"), join(nodeModulesDir, "vitepress"), "dir")
+  symlinkSync(resolvePackageDir("vue"), join(nodeModulesDir, "vue"), "dir")
+}
+
+function ensureContentRuntimeDependencies(contentDir) {
+  const nodeModulesDir = join(contentDir, "node_modules")
+
+  if (existsSync(nodeModulesDir)) {
+    return
+  }
+
+  ensureDir(nodeModulesDir)
+  symlinkSync(resolvePackageDir("vitepress"), join(nodeModulesDir, "vitepress"), "dir")
+  symlinkSync(resolvePackageDir("vue"), join(nodeModulesDir, "vue"), "dir")
+}
+
 export function resolveRepositoryRoot() {
   return REPO_ROOT
 }
@@ -72,7 +98,9 @@ export function prepareStandaloneWorkspace(options = {}) {
   ensureDir(workspaceRoot)
   ensureDir(dirname(cacheDir))
 
+  ensureContentRuntimeDependencies(contentDir)
   mirrorContentEntries(contentDir, workspaceRoot)
+  linkRuntimeDependencies(workspaceRoot)
   generateSnippetPages({
     contentDir,
     outputDir: join(workspaceRoot, "snippets"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notespress",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Generate a VitePress blog site directly from a Markdown notes directory.",
   "license": "MIT",
   "packageManager": "pnpm@10.30.3",