@dogsbay/samples 0.0.0-stage → 0.2.0-beta.126

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @dogsbay/samples
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One-screen sample pages, for the playground and the docs site to share.
+
+| Format | Samples |
+|---|---|
+| Dogsbay Markdown (`md/`) | basics, callouts, tabs and steps, cards and grid, details and accordion, theme band |
+| DITA (`dita/`) | a concept, a task, a reference (with a `<properties>` table), and a topic using the `outputclass` components |
+
+```ts
+import { SAMPLES, sample } from "@dogsbay/samples";
+
+for (const s of SAMPLES) console.log(s.id, s.format, s.title); // "task", "dita", "Publish a site"
+const task = sample("task", "dita")!.source;                    // the DITA source as written
+```
+
+The sources are strings in the module, so it runs in a browser; the same files
+are published as `@dogsbay/samples/md/*.md` and `@dogsbay/samples/dita/*.dita`
+for a site that reads them as files.
+
+Each sample parses with no diagnostic (`dogsbayMdToTree(src, { diagnostics:
+true })`), converts with no note beyond the expected semantic downgrades
+(`ditaTopicToTree(src, { classDefaults: true })`), renders every node with
+`@dogsbay/render-html`, and fits on one screen (45 lines). The tests check all of
+that.
+
+To add or change one, edit the file and run `pnpm --filter @dogsbay/samples
+generate` (which writes `src/samples.ts`); the build refuses a stale module.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @dogsbay/samples — one-screen sample pages in Dogsbay Markdown and DITA,
+ * shared by the docs site and the playground. Browser-safe: the sources are
+ * strings in the module (and also published as files under md/ and dita/).
+ */
+export type { Sample } from "./types.js";
+export { SAMPLES } from "./samples.js";
+import type { Sample } from "./types.js";
+/** The sample with this id and format, or undefined. */
+export declare const sample: (id: string, format?: Sample["format"]) => Sample | undefined;

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SAMPLES } from "./samples.js";
+import { SAMPLES } from "./samples.js";
+/** The sample with this id and format, or undefined. */
+export const sample = (id, format) => SAMPLES.find((s) => s.id === id && (!format || s.format === format));

package/dist/samples.d.ts

@@ -0,0 +1,3 @@
+/** GENERATED by scripts/generate.mjs from md/ and dita/; do not edit. */
+import type { Sample } from "./types.js";
+export declare const SAMPLES: readonly Sample[];

package/dist/samples.js

@@ -0,0 +1,12 @@
+export const SAMPLES = Object.freeze([
+    { "id": "basics", "format": "dogsbay-md", "title": "Markdown basics", "description": "Headings, lists, emphasis, links, code and tables.", "file": "md/basics.md", "source": "---\ntitle: Markdown basics\ndescription: Headings, lists, emphasis, links, code and tables.\n---\n\n# Markdown basics\n\nDogsbay Markdown is **CommonMark** with a few additions. It reads cleanly on\nGitHub and renders richly through Dogsbay. Press :kbd[Ctrl+S] to save.\n\n## Lists\n\n1. Install the CLI\n2. Create a site\n   - pick a theme\n   - add a page\n3. Build it\n\n## Code\n\n```bash title=\"Install\"\nnpm install -g dogsbay\n```\n\n## Tables\n\n| Command | What it does |\n|---|---|\n| `dogsbay site init` | Scaffolds a site |\n| `dogsbay site build` | Builds every target |\n\nRead more in the [CLI guide](https://dogsbay.ai/docs/cli).\n" },
+    { "id": "callouts", "format": "dogsbay-md", "title": "Callouts", "description": "Notes, tips and warnings, in the GitHub form and the directive form.", "file": "md/callouts.md", "source": "---\ntitle: Callouts\ndescription: Notes, tips and warnings, in the GitHub form and the directive form.\n---\n\n# Callouts\n\n> [!NOTE]\n> The GitHub form degrades to a plain quote anywhere else.\n\n> [!TIP]\n> Keep callouts short: one idea each.\n\n> [!WARNING]\n> Deleting a site cannot be undone.\n\n:::caution{title=\"Before you upgrade\"}\nBack up `dogsbay.config.yml`. The directive form takes a custom title.\n:::\n" },
+    { "id": "cards-and-grid", "format": "dogsbay-md", "title": "Cards and grid", "description": "Link cards for navigation, and a grid for mixed content.", "file": "md/cards-and-grid.md", "source": "---\ntitle: Cards and grid\ndescription: Link cards for navigation, and a grid for mixed content.\n---\n\n# Cards and grid\n\n:::cards\n- **[Install](https://dogsbay.ai/docs/install)**\n  Five minutes to a running site.\n\n- **[Write](https://dogsbay.ai/docs/write)**\n  Pages, components and includes.\n\n- **[Publish](https://dogsbay.ai/docs/publish)**\n  Static hosting, sitemaps and search.\n:::\n\n:::link-card{href=\"https://dogsbay.ai/docs/migrate\" title=\"Migrate a site\" description=\"From MkDocs, Docusaurus, DITA and more.\"}\n:::\n\n:::button{href=\"https://dogsbay.ai/docs/install\"}\nGet started\n:::\n" },
+    { "id": "details-and-accordion", "format": "dogsbay-md", "title": "Details and accordion", "description": "Collapsible sections for optional content, and an accordion for questions.", "file": "md/details-and-accordion.md", "source": "---\ntitle: Details and accordion\ndescription: Collapsible sections for optional content, and an accordion for questions.\n---\n\n# Details and accordion\n\n:::details{title=\"Advanced options\"}\nMost readers can skip this. It holds the settings nobody needs on day one.\n:::\n\n:::accordion\nIs Dogsbay free?\n:   Yes. The CLI and the components are open source.\n\nCan I keep my Markdown?\n:   Yes. Dogsbay Markdown is plain Markdown plus a few directives.\n:::\n\nThe beta has a new search :badge[New]{variant=\"success\"} and faster builds.\n" },
+    { "id": "tabs-and-steps", "format": "dogsbay-md", "title": "Tabs and steps", "description": "Tabs from a definition list, and numbered steps.", "file": "md/tabs-and-steps.md", "source": "---\ntitle: Tabs and steps\ndescription: Tabs from a definition list, and numbered steps.\n---\n\n# Tabs and steps\n\n:::tabs\nLinux\n:   ```bash\n    sudo apt install dogsbay\n    ```\n\nmacOS\n:   ```bash\n    brew install dogsbay\n    ```\n\nWindows\n:   ```powershell\n    winget install dogsbay\n    ```\n:::\n\n:::steps\n1. Create a site with `dogsbay site init`.\n2. Write a page in `content/`.\n3. Preview it with `dogsbay site dev`.\n:::\n" },
+    { "id": "theme", "format": "dogsbay-md", "title": "Theme band", "description": "A section drawn with the dark theme.", "file": "md/theme.md", "source": "---\ntitle: Theme band\ndescription: A section drawn with the dark theme.\n---\n\n# Theme band\n\nMost of the page uses the site's theme.\n\n::::theme{name=\"dark\"}\n## Built for teams\n\nReviews, previews and a shared component library.\n\n:::tabs{variant=\"pills\"}\nWriters\n:   Plain Markdown, live preview.\n\nReviewers\n:   Comments on the rendered page.\n:::\n::::\n\nBack on the light page.\n" },
+    { "id": "components", "format": "dita", "title": "Components from DITA", "description": "Standard DITA elements, with an outputclass that picks a component.", "file": "dita/components.dita", "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE topic PUBLIC \"-//OASIS//DTD DITA Topic//EN\" \"topic.dtd\">\n<topic id=\"components\">\n  <title>Components from DITA</title>\n  <shortdesc>Standard DITA elements, with an <codeph>outputclass</codeph> that picks a component.</shortdesc>\n  <body>\n    <dl outputclass=\"db-tabs\">\n      <dlentry>\n        <dt>Linux</dt>\n        <dd><codeblock outputclass=\"language-bash\">sudo apt install dogsbay</codeblock></dd>\n      </dlentry>\n      <dlentry>\n        <dt>macOS</dt>\n        <dd><codeblock outputclass=\"language-bash\">brew install dogsbay</codeblock></dd>\n      </dlentry>\n    </dl>\n    <dl outputclass=\"db-cards tone-info\">\n      <dlentry>\n        <dt><xref href=\"https://dogsbay.ai/docs/install\" scope=\"external\">Install</xref></dt>\n        <dd>Five minutes to a running site.</dd>\n      </dlentry>\n      <dlentry>\n        <dt><xref href=\"https://dogsbay.ai/docs/publish\" scope=\"external\">Publish</xref></dt>\n        <dd>Static hosting, sitemaps and search.</dd>\n      </dlentry>\n    </dl>\n    <p>Search <ph outputclass=\"db-badge tone-success\">New</ph></p>\n    <ol outputclass=\"db-steps\">\n      <li>Create a site.</li>\n      <li>Write a page.</li>\n    </ol>\n    <p><xref href=\"https://dogsbay.ai/docs/install\" scope=\"external\" outputclass=\"db-button outline\">Get started</xref></p>\n    <section id=\"advanced\" outputclass=\"db-details\">\n      <title>Advanced options</title>\n      <p>Most readers can skip this.</p>\n    </section>\n  </body>\n</topic>\n" },
+    { "id": "concept", "format": "dita", "title": "About Dogsbay sites", "description": "A Dogsbay site is a folder of pages and one configuration file.", "file": "dita/concept.dita", "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE concept PUBLIC \"-//OASIS//DTD DITA Concept//EN\" \"concept.dtd\">\n<concept id=\"about-sites\">\n  <title>About Dogsbay sites</title>\n  <shortdesc>A Dogsbay site is a folder of pages and one configuration file.</shortdesc>\n  <conbody>\n    <p>Each page is a topic. The <filepath>dogsbay.config.yml</filepath> file names the site, its\n      theme and where it is published.</p>\n    <note type=\"tip\">\n      <p>Start from <cmdname>dogsbay site init</cmdname>: it writes a working site you can edit.</p>\n    </note>\n    <section>\n      <title>What a build produces</title>\n      <ul>\n        <li>One HTML page per topic</li>\n        <li>A search index and a sitemap</li>\n        <li>A Markdown twin of every page, for agents</li>\n      </ul>\n    </section>\n  </conbody>\n</concept>\n" },
+    { "id": "reference", "format": "dita", "title": "Configuration keys", "description": "The keys most sites set in dogsbay.config.yml.", "file": "dita/reference.dita", "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE reference PUBLIC \"-//OASIS//DTD DITA Reference//EN\" \"reference.dtd\">\n<reference id=\"config-keys\">\n  <title>Configuration keys</title>\n  <shortdesc>The keys most sites set in <filepath>dogsbay.config.yml</filepath>.</shortdesc>\n  <refbody>\n    <properties>\n      <prophead><proptypehd>Key</proptypehd><propvaluehd>Default</propvaluehd><propdeschd>Meaning</propdeschd></prophead>\n      <property><proptype>title</proptype><propvalue>none</propvalue><propdesc>The site's name, in the header and the page titles.</propdesc></property>\n      <property><proptype>theme</proptype><propvalue>default</propvalue><propdesc>The token set: <codeph>default</codeph> or <codeph>material</codeph>.</propdesc></property>\n      <property><proptype>poweredBy</proptype><propvalue>true</propvalue><propdesc>Show the footer mark.</propdesc></property>\n    </properties>\n    <section>\n      <title>Example</title>\n      <codeblock outputclass=\"language-yaml\">title: My docs\ntheme: material</codeblock>\n    </section>\n  </refbody>\n</reference>\n" },
+    { "id": "task", "format": "dita", "title": "Publish a site", "description": "Build the site and copy the output to any static host.", "file": "dita/task.dita", "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE task PUBLIC \"-//OASIS//DTD DITA Task//EN\" \"task.dtd\">\n<task id=\"publish-site\">\n  <title>Publish a site</title>\n  <shortdesc>Build the site and copy the output to any static host.</shortdesc>\n  <taskbody>\n    <prereq><p>Install the CLI: <codeph>npm install -g dogsbay</codeph>.</p></prereq>\n    <steps>\n      <step><cmd>Open a terminal in the site folder.</cmd></step>\n      <step>\n        <cmd>Build the site.</cmd>\n        <info><codeblock outputclass=\"language-bash\">dogsbay site build</codeblock></info>\n      </step>\n      <step>\n        <cmd>Choose <menucascade><uicontrol>File</uicontrol><uicontrol>Upload</uicontrol></menucascade>\n          in your host's console, and upload the <filepath>dist</filepath> folder.</cmd>\n        <stepresult><p>The site is live at your host's address.</p></stepresult>\n      </step>\n    </steps>\n    <result><p>Readers see the new pages straight away.</p></result>\n  </taskbody>\n</task>\n" },
+]);

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+/** One sample page: its source as written, and what it is. */
+export interface Sample {
+    /** The file name without its extension: `basics`, `task`. */
+    id: string;
+    /** `dogsbay-md` (convert with dogsbayMdToTree) or `dita` (ditaTopicToTree). */
+    format: "dogsbay-md" | "dita";
+    title: string;
+    description: string;
+    /** Its path in this package (`md/basics.md`), also published as a file. */
+    file: string;
+    source: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dita/components.dita

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
+<topic id="components">
+  <title>Components from DITA</title>
+  <shortdesc>Standard DITA elements, with an <codeph>outputclass</codeph> that picks a component.</shortdesc>
+  <body>
+    <dl outputclass="db-tabs">
+      <dlentry>
+        <dt>Linux</dt>
+        <dd><codeblock outputclass="language-bash">sudo apt install dogsbay</codeblock></dd>
+      </dlentry>
+      <dlentry>
+        <dt>macOS</dt>
+        <dd><codeblock outputclass="language-bash">brew install dogsbay</codeblock></dd>
+      </dlentry>
+    </dl>
+    <dl outputclass="db-cards tone-info">
+      <dlentry>
+        <dt><xref href="https://dogsbay.ai/docs/install" scope="external">Install</xref></dt>
+        <dd>Five minutes to a running site.</dd>
+      </dlentry>
+      <dlentry>
+        <dt><xref href="https://dogsbay.ai/docs/publish" scope="external">Publish</xref></dt>
+        <dd>Static hosting, sitemaps and search.</dd>
+      </dlentry>
+    </dl>
+    <p>Search <ph outputclass="db-badge tone-success">New</ph></p>
+    <ol outputclass="db-steps">
+      <li>Create a site.</li>
+      <li>Write a page.</li>
+    </ol>
+    <p><xref href="https://dogsbay.ai/docs/install" scope="external" outputclass="db-button outline">Get started</xref></p>
+    <section id="advanced" outputclass="db-details">
+      <title>Advanced options</title>
+      <p>Most readers can skip this.</p>
+    </section>
+  </body>
+</topic>

package/dita/concept.dita

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="about-sites">
+  <title>About Dogsbay sites</title>
+  <shortdesc>A Dogsbay site is a folder of pages and one configuration file.</shortdesc>
+  <conbody>
+    <p>Each page is a topic. The <filepath>dogsbay.config.yml</filepath> file names the site, its
+      theme and where it is published.</p>
+    <note type="tip">
+      <p>Start from <cmdname>dogsbay site init</cmdname>: it writes a working site you can edit.</p>
+    </note>
+    <section>
+      <title>What a build produces</title>
+      <ul>
+        <li>One HTML page per topic</li>
+        <li>A search index and a sitemap</li>
+        <li>A Markdown twin of every page, for agents</li>
+      </ul>
+    </section>
+  </conbody>
+</concept>

package/dita/reference.dita

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
+<reference id="config-keys">
+  <title>Configuration keys</title>
+  <shortdesc>The keys most sites set in <filepath>dogsbay.config.yml</filepath>.</shortdesc>
+  <refbody>
+    <properties>
+      <prophead><proptypehd>Key</proptypehd><propvaluehd>Default</propvaluehd><propdeschd>Meaning</propdeschd></prophead>
+      <property><proptype>title</proptype><propvalue>none</propvalue><propdesc>The site's name, in the header and the page titles.</propdesc></property>
+      <property><proptype>theme</proptype><propvalue>default</propvalue><propdesc>The token set: <codeph>default</codeph> or <codeph>material</codeph>.</propdesc></property>
+      <property><proptype>poweredBy</proptype><propvalue>true</propvalue><propdesc>Show the footer mark.</propdesc></property>
+    </properties>
+    <section>
+      <title>Example</title>
+      <codeblock outputclass="language-yaml">title: My docs
+theme: material</codeblock>
+    </section>
+  </refbody>
+</reference>

package/dita/task.dita

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
+<task id="publish-site">
+  <title>Publish a site</title>
+  <shortdesc>Build the site and copy the output to any static host.</shortdesc>
+  <taskbody>
+    <prereq><p>Install the CLI: <codeph>npm install -g dogsbay</codeph>.</p></prereq>
+    <steps>
+      <step><cmd>Open a terminal in the site folder.</cmd></step>
+      <step>
+        <cmd>Build the site.</cmd>
+        <info><codeblock outputclass="language-bash">dogsbay site build</codeblock></info>
+      </step>
+      <step>
+        <cmd>Choose <menucascade><uicontrol>File</uicontrol><uicontrol>Upload</uicontrol></menucascade>
+          in your host's console, and upload the <filepath>dist</filepath> folder.</cmd>
+        <stepresult><p>The site is live at your host's address.</p></stepresult>
+      </step>
+    </steps>
+    <result><p>Readers see the new pages straight away.</p></result>
+  </taskbody>
+</task>

package/md/basics.md

@@ -0,0 +1,32 @@
+---
+title: Markdown basics
+description: Headings, lists, emphasis, links, code and tables.
+---
+
+# Markdown basics
+
+Dogsbay Markdown is **CommonMark** with a few additions. It reads cleanly on
+GitHub and renders richly through Dogsbay. Press :kbd[Ctrl+S] to save.
+
+## Lists
+
+1. Install the CLI
+2. Create a site
+   - pick a theme
+   - add a page
+3. Build it
+
+## Code
+
+```bash title="Install"
+npm install -g dogsbay
+```
+
+## Tables
+
+| Command | What it does |
+|---|---|
+| `dogsbay site init` | Scaffolds a site |
+| `dogsbay site build` | Builds every target |
+
+Read more in the [CLI guide](https://dogsbay.ai/docs/cli).

package/md/callouts.md

@@ -0,0 +1,19 @@
+---
+title: Callouts
+description: Notes, tips and warnings, in the GitHub form and the directive form.
+---
+
+# Callouts
+
+> [!NOTE]
+> The GitHub form degrades to a plain quote anywhere else.
+
+> [!TIP]
+> Keep callouts short: one idea each.
+
+> [!WARNING]
+> Deleting a site cannot be undone.
+
+:::caution{title="Before you upgrade"}
+Back up `dogsbay.config.yml`. The directive form takes a custom title.
+:::

package/md/cards-and-grid.md

@@ -0,0 +1,24 @@
+---
+title: Cards and grid
+description: Link cards for navigation, and a grid for mixed content.
+---
+
+# Cards and grid
+
+:::cards
+- **[Install](https://dogsbay.ai/docs/install)**
+  Five minutes to a running site.
+
+- **[Write](https://dogsbay.ai/docs/write)**
+  Pages, components and includes.
+
+- **[Publish](https://dogsbay.ai/docs/publish)**
+  Static hosting, sitemaps and search.
+:::
+
+:::link-card{href="https://dogsbay.ai/docs/migrate" title="Migrate a site" description="From MkDocs, Docusaurus, DITA and more."}
+:::
+
+:::button{href="https://dogsbay.ai/docs/install"}
+Get started
+:::

package/md/details-and-accordion.md

@@ -0,0 +1,20 @@
+---
+title: Details and accordion
+description: Collapsible sections for optional content, and an accordion for questions.
+---
+
+# Details and accordion
+
+:::details{title="Advanced options"}
+Most readers can skip this. It holds the settings nobody needs on day one.
+:::
+
+:::accordion
+Is Dogsbay free?
+:   Yes. The CLI and the components are open source.
+
+Can I keep my Markdown?
+:   Yes. Dogsbay Markdown is plain Markdown plus a few directives.
+:::
+
+The beta has a new search :badge[New]{variant="success"} and faster builds.

package/md/tabs-and-steps.md

@@ -0,0 +1,29 @@
+---
+title: Tabs and steps
+description: Tabs from a definition list, and numbered steps.
+---
+
+# Tabs and steps
+
+:::tabs
+Linux
+:   ```bash
+    sudo apt install dogsbay
+    ```
+
+macOS
+:   ```bash
+    brew install dogsbay
+    ```
+
+Windows
+:   ```powershell
+    winget install dogsbay
+    ```
+:::
+
+:::steps
+1. Create a site with `dogsbay site init`.
+2. Write a page in `content/`.
+3. Preview it with `dogsbay site dev`.
+:::

package/md/theme.md

@@ -0,0 +1,24 @@
+---
+title: Theme band
+description: A section drawn with the dark theme.
+---
+
+# Theme band
+
+Most of the page uses the site's theme.
+
+::::theme{name="dark"}
+## Built for teams
+
+Reviews, previews and a shared component library.
+
+:::tabs{variant="pills"}
+Writers
+:   Plain Markdown, live preview.
+
+Reviewers
+:   Comments on the rendered page.
+:::
+::::
+
+Back on the light page.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@dogsbay/samples",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0-beta.126",
+  "description": "One-screen sample pages in Dogsbay Markdown and DITA (concept, task, reference, components), shared by the docs site and the playground. Browser-safe; also shipped as files",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/samples"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./md/*": "./md/*",
+    "./dita/*": "./dita/*"
+  },
+  "files": [
+    "dist",
+    "md",
+    "dita",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.9.5",
+    "esbuild": "0.28.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@dogsbay/format-dita": "0.2.0-beta.126",
+    "@dogsbay/types": "0.2.0-beta.126",
+    "@dogsbay/render-html": "0.2.0-beta.126",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.126"
+  },
+  "scripts": {
+    "build": "node scripts/generate.mjs --check && tsc",
+    "generate": "node scripts/generate.mjs",
+    "test": "vitest run"
+  }
 }