dogsbay 0.2.0-beta.40 → 0.2.0-beta.42

package/dist/commands/migrate-mkdocs.js

@@ -131,15 +131,28 @@ export async function migrateMkdocs(source, options) {
     //    makes the migrated config self-documenting. NO `output:`
     //    field — the default (./astro) is what we want; flat layout
     //    (`output: "."`) triggers a rebuild loop in `site dev`.
-    const siteUrl = config.site_url || undefined;
+    // site.url is NOT inherited from the source mkdocs.yml. A
+    // migration almost always moves to a new host, so copying the
+    // source's site_url silently bakes the wrong origin into
+    // robots.txt, sitemap, canonical tags, and llms.txt. The user
+    // supplies the destination explicitly with --site-url; absent,
+    // site.url is left unset and the build emits relative URLs.
+    // sourceSiteUrl is kept only to warn the user it was dropped.
+    const sourceSiteUrl = config.site_url || undefined;
+    const siteUrl = options.siteUrl || undefined;
     const repoUrl = config.repo_url || undefined;
+    // --base-path controls where docs sit under the host. Default
+    // /docs (matches every scaffolded dogsbay site); pass --base-path
+    // "" to serve at the host root — common for a dedicated repo or
+    // GitHub Pages project site.
+    const basePath = options.basePath !== undefined ? options.basePath : "/docs";
     const siteDescription = config.site_description || undefined;
     const dogsbayConfig = {
         schemaVersion: 1,
         site: {
             name: siteName,
             url: siteUrl,
-            basePath: "/docs",
+            basePath,
             description: siteDescription,
             repoUrl,
         },
@@ -153,6 +166,14 @@ export async function migrateMkdocs(source, options) {
     };
     writeFileSync(join(outputDir, "dogsbay.config.yml"), serializeConfig(dogsbayConfig, "yaml"));
     console.log(pc.green(`Wrote`) + ` dogsbay.config.yml`);
+    if (sourceSiteUrl && !siteUrl) {
+        console.log(pc.yellow(`Note:`) +
+            ` source site_url (${sourceSiteUrl}) was not carried over —` +
+            ` a migration moves hosts.`);
+        console.log(`      Set site.url in dogsbay.config.yml (or re-run with` +
+            ` --site-url) so robots.txt,`);
+        console.log(`      sitemap, and llms.txt point at your host.`);
+    }
     // 6. Scaffold the Astro project under ./astro/ (theme,
     //    package.json, astro.config.mjs, tsconfig, copied UI
     //    components). Same emitter `dogsbay site init` uses, just
@@ -160,7 +181,7 @@ export async function migrateMkdocs(source, options) {
     emitSiteScaffold(astroDir, siteName, {
         siteName,
         siteUrl,
-        basePath: "/docs",
+        basePath,
         repoUrl,
         llmsTxt: true,
         mdMirror: true,
@@ -187,6 +208,9 @@ export async function migrateMkdocs(source, options) {
         pageCount,
         assetCount,
         lossy,
+        siteUrl,
+        sourceSiteUrl,
+        basePath,
     }));
     console.log(pc.green(`Wrote`) + ` MIGRATION.md`);
     if (!options.quiet) {
@@ -785,7 +809,7 @@ function labelFromPath(path) {
 }
 // ── MIGRATION.md ────────────────────────────────────────
 function buildMigrationNotes(args) {
-    const { sourceDir, outputDir, siteName, pageCount, assetCount, lossy } = args;
+    const { sourceDir, outputDir, siteName, pageCount, assetCount, lossy, siteUrl, sourceSiteUrl, basePath, } = args;
     const lines = [
         `# Migration: ${siteName}`,
         "",
@@ -811,19 +835,22 @@ function buildMigrationNotes(args) {
         "npx dogsbay site dev        # watch + preview",
         "```",
         "",
-        "## Re-running the migration",
-        "",
-        "If you find a regression and we ship a fix, re-run with `--force`:",
-        "",
-        "```bash",
-        `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`,
-        "```",
-        "",
-        "Note that `--force` overwrites all generated files; any hand edits",
-        "to `./content/*.md` since the last migration will be lost. Commit",
-        "your work first.",
-        "",
     ];
+    // Site URL section — the destination URL is not inherited from the
+    // source mkdocs.yml, so spell out what was written and what (if
+    // anything) was dropped.
+    lines.push("## Site URL", "");
+    if (siteUrl) {
+        lines.push(`\`site.url\` is set to \`${siteUrl}\` (from \`--site-url\`).`, `\`site.basePath\` is \`${basePath || '""'}\`. robots.txt, the`, "sitemap, canonical tags, and llms.txt all derive from these —", "edit `dogsbay.config.yml` and rebuild to change them.", "");
+    }
+    else {
+        lines.push("`site.url` was left **unset** — a migration moves hosts, so the", "source's `site_url` is intentionally not carried over. The build", "emits relative URLs until you set it.", "");
+        if (sourceSiteUrl) {
+            lines.push(`The source \`mkdocs.yml\` had \`site_url: ${sourceSiteUrl}\` —`, "that points at the *old* host and was dropped on purpose.", "");
+        }
+        lines.push("Set the destination URL in `dogsbay.config.yml`:", "", "```yaml", "site:", "  url: https://you.github.io/your-repo   # drives sitemap, llms.txt, canonical", `  basePath: ${basePath || '""'}`, "```", "", "Or re-run the migration with `--site-url` (and optionally", "`--base-path`).", "");
+    }
+    lines.push("## Re-running the migration", "", "If you find a regression and we ship a fix, re-run with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`, "```", "", "Note that `--force` overwrites all generated files; any hand edits", "to `./content/*.md` since the last migration will be lost. Commit", "your work first.", "");
     if (lossy.length > 0) {
         lines.push("## Known limitations", "");
         lines.push("The following files have content that didn't fully round-trip", "into Dogsbay-MD. Review each one and fix manually:", "");

package/dist/index.js

@@ -184,6 +184,13 @@ program
     .argument("<source>", "Path to MkDocs project (containing mkdocs.yml)")
     .option("-o, --output <dir>", "Output directory (default: {source}-dogsbay)")
     .option("--force", "Overwrite an existing Dogsbay site at the output dir")
+    .option("--site-url <url>", "Canonical URL of the destination site (e.g. " +
+    "https://you.github.io/repo). Drives robots.txt, sitemap, " +
+    "canonical tags, and llms.txt. NOT inherited from the source " +
+    "mkdocs.yml — a migration moves hosts.")
+    .option("--base-path <path>", 'Path under the host where docs are served (default "/docs"). ' +
+    'Pass --base-path "" to serve at the host root — common for a ' +
+    "dedicated repo / GitHub Pages project site.")
     .option("--inline-autodoc", "Resolve mkdocstrings ::: directives at migration time (snapshot). " +
     "Default is :::autodoc directives that site-build resolves on " +
     "every build (live re-rendering).")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.40",
+  "version": "0.2.0-beta.42",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,15 +32,15 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/autodoc-python": "0.2.0-beta.38",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.40",
-    "@dogsbay/format-astro": "0.2.0-beta.40",
-    "@dogsbay/format-obsidian": "0.2.0-beta.40",
-    "@dogsbay/format-starlight": "0.2.0-beta.40",
-    "@dogsbay/format-mdx": "0.2.0-beta.40",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.40",
-    "@dogsbay/types": "0.2.0-beta.40",
-    "@dogsbay/format-openapi": "0.2.0-beta.40"
+    "@dogsbay/autodoc-python": "0.2.0-beta.42",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.42",
+    "@dogsbay/format-obsidian": "0.2.0-beta.42",
+    "@dogsbay/format-astro": "0.2.0-beta.42",
+    "@dogsbay/format-mdx": "0.2.0-beta.42",
+    "@dogsbay/format-starlight": "0.2.0-beta.42",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.42",
+    "@dogsbay/format-openapi": "0.2.0-beta.42",
+    "@dogsbay/types": "0.2.0-beta.42"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",

package/skills/platform/migration-shape/SKILL.md

@@ -62,6 +62,39 @@ This was learned the hard way during Phase 3 of
 emitted `output: "."` and `dogsbay site dev` rebuild-looped on the
 result. The fix was to revert to the standard `output: "./astro"`.
 
+### Destination URL — supplied, not inherited
+
+**Do NOT copy the source format's site URL into `site.url`.** A
+migration almost always moves the docs to a *new* host — GitHub
+Pages, a Cloudflare project, a custom domain. The source's
+`site_url` (MkDocs), `url` (Jekyll `_config.yml`), `baseURL`
+(Hugo), etc. points at the *old* host.
+
+`site.url` feeds `robots.txt`, the sitemap XML, the `Sitemap:` /
+`Llms-Txt:` lines, canonical tags, `llms.txt` absolute URLs, and
+Astro's `site` / `base`. Inheriting the wrong origin silently
+breaks every one of those — and the breakage only shows up after
+a build, in generated files the user doesn't normally read.
+
+**Required:**
+- Migration commands take a `--site-url <url>` flag. Its value
+  goes to `dogsbay.config.yml`'s `site.url` *and* the scaffold
+  emitter's `siteUrl` option. The URL may carry a path component
+  (`https://you.github.io/repo`); `format-astro`'s `parseSiteUrl`
+  splits it into Astro `site` (origin) + `base` (urlBase) — this
+  is exactly how GitHub Pages **project** sites work.
+- Take a `--base-path <path>` flag too. Default `/docs`; `""`
+  serves at the host root. Check `!== undefined` (not truthiness)
+  so the empty string is honoured.
+- When `--site-url` is absent, leave `site.url` **unset** (the
+  build degrades cleanly to relative URLs) — do NOT fall back to
+  the source value.
+- Keep the dropped source URL only to (a) print a one-line note
+  after writing the config and (b) record it in `MIGRATION.md`'s
+  "Site URL" section so the user knows what to set.
+- The *code* repo URL (`repo_url` etc.) **is** inherited — that
+  doesn't change in a docs migration.
+
 ## 2. Asset folder (`content/_assets/`)
 
 All images, diagrams, screenshots, icons, PDFs, and downloadable
@@ -247,6 +280,7 @@ Every migration command MUST have a fixture test asserting all of:
 | `<output>/content/nav.json` does NOT exist | Avoid loader precedence trap |
 | `<output>/dogsbay.config.yml` has `sources: [{ path: ./content, from: dogsbay-md }]` | Config wires content to source |
 | `<output>/dogsbay.config.yml` does NOT set `output:` | Use default `./astro` |
+| `site.url` reflects `--site-url`, NOT the source's URL; absent → unset | Destination URL not inherited |
 | `<output>/astro/package.json` exists | Scaffold under astro/ |
 | `<output>/astro/astro.config.mjs` exists | Scaffold under astro/ |
 | `<output>/astro/src/styles/theme.css` exists | Scaffold under astro/ |