dogsbay 0.2.0-beta.3 → 0.2.0-beta.5

package/dist/commands/site-init.js

@@ -108,54 +108,204 @@ export async function siteInit(targetDir, options) {
         astroOpts.local = true;
     emitSiteScaffold(outputDir, config.site.name, astroOpts, true);
     // Seed starter content so the first `dogsbay site build` succeeds
-    // without manual intervention. Only writes when this is a fresh
-    // init (writeConfig=true; scaffold-only consumers already have
-    // content) and the content dir doesn't exist yet — never
-    // overwrites user files. See plans/beta-launch-followups.md.
-    let starterContentPath = null;
+    // without manual intervention. Writes index.md, getting-started.md,
+    // and nav.yml when (a) this is a fresh init (writeConfig=true;
+    // scaffold-only consumers already have content) and (b) the
+    // content dir doesn't exist yet. Never overwrites user files. See
+    // plans/beta-launch-followups.md.
+    let starterContentPaths = [];
     if (writeConfig) {
-        starterContentPath = seedStarterContent(absTarget, config);
+        starterContentPaths = seedStarterContent(absTarget, config);
     }
-    printNextSteps(absTarget, outputDir, config, starterContentPath);
+    printNextSteps(absTarget, outputDir, config, starterContentPaths);
 }
 /**
- * Create a starter `<content>/index.md` if the content dir doesn't
- * already exist. Returns the path written, or null when nothing
- * was created (dir already populated). Never overwrites.
+ * Create a starter content set if the content dir doesn't already
+ * exist. Writes `index.md`, `getting-started.md`, and `nav.yml`
+ * so the user has a working multi-page site with a navigation
+ * structure to learn from. Returns the list of paths written, or
+ * an empty array when nothing was created. Never overwrites.
  */
 function seedStarterContent(absTarget, config) {
     const sources = config.content.sources ?? [];
     const first = sources[0];
     if (!first?.path)
-        return null;
+        return [];
     const contentDir = isAbsolute(first.path)
         ? first.path
         : join(absTarget, first.path);
     if (existsSync(contentDir))
-        return null; // user already has content
+        return []; // user already has content
     mkdirSync(contentDir, { recursive: true });
+    const written = [];
+    const siteName = config.site.name?.trim() || "your documentation site";
+    const basePath = config.site.basePath ?? "/docs";
     const indexPath = join(contentDir, "index.md");
     writeFileSync(indexPath, `---
-title: ${config.site.name || "Welcome"}
+title: Welcome
 description: Edit content/index.md to get started.
 ---
 
-# ${config.site.name || "Welcome"}
+# Welcome
 
-This is your starter page. Replace this content with your own
-markdown — every \`.md\` file under \`content/\` becomes a page.
+This is the starting point of ${siteName}, built with
+[Dogsbay](https://github.com/dogsbay/dogsbay). Replace this
+content with your own — every \`.md\` file under \`content/\` becomes
+a page.
 
-## What's next
+> [!TIP]
+> Edit this file (\`content/index.md\`) and save. The dev server
+> reloads automatically.
 
-- Edit this file (\`content/index.md\`) to change the home page.
-- Add more \`.md\` files alongside it for additional pages.
-- Run \`dogsbay site dev\` to preview live as you edit.
-- See \`dogsbay.config.yml\` for site-wide settings (theme, agent
-  readiness, deploy target, etc.).
+## Get started in 60 seconds
 
-For the full reference, see https://github.com/dogsbay/dogsbay.
+:::steps
+1. **Edit a page**
+   Open \`content/index.md\` and change something. Save — the
+   preview updates live.
+
+2. **Add a page**
+   Create \`content/about.md\` with frontmatter and a heading.
+
+3. **Wire it in**
+   Add the new page to \`content/nav.yml\` so it shows up in the
+   sidebar.
+:::
+
+## Where to go next
+
+:::cards
+- **[Getting started](${basePath}/getting-started)**
+  Three-minute orientation to editing, adding, and grouping pages.
+
+- **[Configuration](${basePath}/getting-started)**
+  Site name, theme, base path, and per-source settings live in
+  \`dogsbay.config.yml\`.
+
+- **[Source on GitHub](https://github.com/dogsbay/dogsbay)**
+  Star, browse, file an issue, or follow the roadmap.
+
+- **[Plugins](https://github.com/dogsbay/dogsbay/tree/main/docs)**
+  Image zoom, TypeDoc, and your own — the plugin API is small,
+  typed, and explicit.
+:::
+
+## Markdown that does more
+
+Cards, steps, tabs, callouts, fenced code — Dogsbay markdown is
+a small superset of CommonMark with directives for the components
+docs sites need most. Here's the same config in two formats:
+
+:::tabs
+YAML
+:   \`\`\`yaml
+    site:
+      name: ${siteName.includes("documentation") ? "Acme Docs" : siteName}
+      url: https://example.com
+    content:
+      sources:
+        - path: ./content
+          from: dogsbay-md
+    \`\`\`
+
+JSON
+:   \`\`\`json
+    {
+      "site": { "name": "${siteName.includes("documentation") ? "Acme Docs" : siteName}" },
+      "content": {
+        "sources": [{ "path": "./content", "from": "dogsbay-md" }]
+      }
+    }
+    \`\`\`
+:::
+
+For the full markdown reference, see
+[github.com/dogsbay/dogsbay](https://github.com/dogsbay/dogsbay).
+`);
+    written.push(indexPath);
+    const gettingStartedPath = join(contentDir, "getting-started.md");
+    writeFileSync(gettingStartedPath, `---
+title: Getting started
+description: Quick orientation for new contributors.
+---
+
+# Getting started
+
+Three minutes to your first edit. Powered by
+[Dogsbay](https://github.com/dogsbay/dogsbay).
+
+## 1. Edit a page
+
+Open \`content/index.md\` in your editor and change something.
+Save — the dev server reloads automatically.
+
+## 2. Add a page
+
+Create a new file like \`content/about.md\`:
+
+\`\`\`md
+---
+title: About
+---
+
+# About
+
+Whatever you want to say here.
+\`\`\`
+
+Then add it to \`content/nav.yml\` so it appears in the sidebar.
+Each entry is a single-key map — key = label, value = file path:
+
+\`\`\`yaml
+- About: about.md
+\`\`\`
+
+External URLs work the same way:
+
+\`\`\`yaml
+- GitHub: https://github.com/your-org/your-repo
+\`\`\`
+
+## 3. Group pages
+
+To create a section in the sidebar, give the entry a list of
+children instead of a single file:
+
+\`\`\`yaml
+- Guides:
+    - Configuration: guides/configuration.md
+    - Deployment: guides/deployment.md
+\`\`\`
+
+The folder structure under \`content/\` doesn't have to match the
+nav — but it usually does, because it makes URLs predictable.
+`);
+    written.push(gettingStartedPath);
+    const navPath = join(contentDir, "nav.yml");
+    writeFileSync(navPath, `# Sidebar navigation. Loaded by Dogsbay automatically — name this
+# file nav.yml, nav.yaml, or nav.json (in that order of precedence).
+#
+# Each entry is a single-key map. The key is the sidebar label.
+# The value is one of:
+#   - a file path (relative to content/, e.g. "guide.md")
+#   - an absolute URL (e.g. "https://...")
+#   - a list of child entries (creates a group)
+#
+# Examples:
+#   - Home: index.md                       # leaf — file path
+#   - GitHub: https://github.com/…         # leaf — external URL
+#   - Guides:                              # group — children below
+#       - Configuration: guides/config.md
+#       - Deployment: guides/deploy.md
+#
+# Edit freely as you add or rearrange pages. See
+# https://github.com/dogsbay/dogsbay for the full nav-file reference.
+
+- Home: index.md
+- Getting started: getting-started.md
 `);
-    return indexPath;
+    written.push(navPath);
+    return written;
 }
 // ─── Resolution: flags + prompts → DogsbayConfig ─────────────────────────
 async function resolveConfig(opts, interactive) {
@@ -401,14 +551,14 @@ function findExistingConfig(dir) {
     }
     return null;
 }
-function printNextSteps(absTarget, outputDir, config, starterContentPath) {
+function printNextSteps(absTarget, outputDir, config, starterContentPaths) {
     void config;
     const sameDir = absTarget === outputDir;
     console.log("");
     console.log(pc.green("Wrote:"));
     console.log(`  ${absTarget}/dogsbay.config.yml`);
-    if (starterContentPath) {
-        console.log(`  ${starterContentPath}`);
+    for (const p of starterContentPaths) {
+        console.log(`  ${p}`);
     }
     console.log(`  ${outputDir}/package.json`);
     console.log(`  ${outputDir}/astro.config.mjs`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.5",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -30,14 +30,14 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.3",
-    "@dogsbay/format-obsidian": "0.2.0-beta.3",
-    "@dogsbay/format-mdx": "0.2.0-beta.3",
-    "@dogsbay/format-starlight": "0.2.0-beta.3",
-    "@dogsbay/format-astro": "0.2.0-beta.3",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.3",
-    "@dogsbay/format-openapi": "0.2.0-beta.3",
-    "@dogsbay/types": "0.2.0-beta.3"
+    "@dogsbay/format-mkdocs": "0.2.0-beta.5",
+    "@dogsbay/format-astro": "0.2.0-beta.5",
+    "@dogsbay/format-obsidian": "0.2.0-beta.5",
+    "@dogsbay/format-mdx": "0.2.0-beta.5",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.5",
+    "@dogsbay/format-starlight": "0.2.0-beta.5",
+    "@dogsbay/format-openapi": "0.2.0-beta.5",
+    "@dogsbay/types": "0.2.0-beta.5"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",