@jasonshimmy/vite-plugin-cer-app 0.20.5 → 0.21.0

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [v0.21.0] - 2026-04-12
+
+- feat: add support for numeric ordering prefixes in content paths and update related tests (ffb0bc8)
+
 ## [v0.20.5] - 2026-04-12
 
 - fix: enhance hydration handling and data caching in usePageData and routing middleware (305ae7f)

package/README.md

@@ -210,6 +210,28 @@ component('page-about', () => {
 
 ---
 
+## Content Layer
+
+Drop Markdown and JSON files into `content/` and query them with `queryContent()`.
+
+Numeric ordering prefixes are supported on both directories and files. A leading `NN.` is stripped from the public content path, which lets you keep source-tree ordering without leaking the prefix into URLs:
+
+```text
+content/
+  01.docs/
+    01.getting-started.md   -> /docs/getting-started
+    02.routing.md           -> /docs/routing
+  02.blog/
+    01.index.md             -> /blog
+    02.2026-04-01-hello.md  -> /blog/hello
+```
+
+Date-prefixed filenames still work the same way after the numeric prefix is removed.
+
+See [docs/content.md](docs/content.md) for the full content-layer API and examples.
+
+---
+
 ## Documentation
 
 | Guide | Description |

package/commits.txt

@@ -1 +1 @@
-- fix: enhance hydration handling and data caching in usePageData and routing middleware (305ae7f)
+- feat: add support for numeric ordering prefixes in content paths and update related tests (ffb0bc8)

package/dist/plugin/content/path-utils.d.ts

@@ -4,12 +4,15 @@
  * Rules:
  * - Strip the content dir prefix
  * - Strip the file extension
+ * - Strip `NN.` numeric ordering prefixes from all path segments
  * - Strip `/index` suffix (so blog/index.md → /blog)
  * - Strip `YYYY-MM-DD-` date prefix from the final slug segment
  *
  * Examples:
  *   index.md                → /
+ *   01.about.md             → /about
  *   about.md                → /about
+ *   01.blog/02.hello.md     → /blog/hello
  *   blog/index.md           → /blog
  *   blog/2026-04-03-hello.md → /blog/hello
  *   docs/getting-started.md  → /docs/getting-started

package/dist/plugin/content/path-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/plugin/content/path-utils.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAyB9E"}
+{"version":3,"file":"path-utils.d.ts","sourceRoot":"","sources":["../../../src/plugin/content/path-utils.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA0B9E"}

package/dist/plugin/content/path-utils.js

@@ -1,16 +1,22 @@
 import { relative } from 'pathe';
+function stripNumericPrefix(segment) {
+    return segment.replace(/^\d+\./, '');
+}
 /**
  * Maps a content file path to a `_path` URL path.
  *
  * Rules:
  * - Strip the content dir prefix
  * - Strip the file extension
+ * - Strip `NN.` numeric ordering prefixes from all path segments
  * - Strip `/index` suffix (so blog/index.md → /blog)
  * - Strip `YYYY-MM-DD-` date prefix from the final slug segment
  *
  * Examples:
  *   index.md                → /
+ *   01.about.md             → /about
  *   about.md                → /about
+ *   01.blog/02.hello.md     → /blog/hello
  *   blog/index.md           → /blog
  *   blog/2026-04-03-hello.md → /blog/hello
  *   docs/getting-started.md  → /docs/getting-started
@@ -21,8 +27,9 @@ export function fileToContentPath(filePath, contentDir) {
     let rel = relative(contentDir, filePath);
     rel = rel.replace(/\.(md|json)$/, '');
     // Split into segments
-    const segments = rel.split('/');
-    // Strip date prefix (YYYY-MM-DD-) from the last segment
+    const segments = rel.split('/').map(stripNumericPrefix);
+    // Strip date prefix (YYYY-MM-DD-) from the last segment after removing any
+    // numeric ordering prefix (for example 01.2026-04-03-hello.md → /hello).
     const last = segments[segments.length - 1];
     const stripped = last.replace(/^\d{4}-\d{2}-\d{2}-/, '');
     segments[segments.length - 1] = stripped;

package/dist/plugin/content/path-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/plugin/content/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhC;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,UAAkB;IACpE,mDAAmD;IACnD,IAAI,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IACxC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;IAErC,sBAAsB;IACtB,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAE/B,wDAAwD;IACxD,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAA;IACxD,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAA;IAExC,+DAA+D;IAC/D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACrE,QAAQ,CAAC,GAAG,EAAE,CAAA;IAChB,CAAC;IAED,qDAAqD;IACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAClC,CAAC"}
+{"version":3,"file":"path-utils.js","sourceRoot":"","sources":["../../../src/plugin/content/path-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhC,SAAS,kBAAkB,CAAC,OAAe;IACzC,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,UAAkB;IACpE,mDAAmD;IACnD,IAAI,GAAG,GAAG,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IACxC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAA;IAErC,sBAAsB;IACtB,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;IAEvD,2EAA2E;IAC3E,yEAAyE;IACzE,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAA;IACxD,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAA;IAExC,+DAA+D;IAC/D,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACrE,QAAQ,CAAC,GAAG,EAAE,CAAA;IAChB,CAAC;IAED,qDAAqD;IACrD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;QACrD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAClC,CAAC"}

package/docs/content.md

@@ -28,6 +28,15 @@ content/
     getting-started.md
 ```
 
+Numeric ordering prefixes are also supported on both directories and files. A leading `NN.` is used for ordering in the source tree but stripped from the public content path:
+
+```
+content/
+  01.docs/
+    01.getting-started.md   -> /docs/getting-started
+    02.routing.md           -> /docs/routing
+```
+
 ### 2. Query content in a page
 
 ```ts
@@ -145,6 +154,17 @@ Filenames starting with `YYYY-MM-DD-` have the date prefix stripped when computi
 content/blog/2026-04-01-hello.md  →  _path: '/blog/hello'
 ```
 
+### Numeric ordering prefixes
+
+Directories and filenames starting with `NN.` have that numeric prefix stripped from the computed content path. This lets you control source-tree ordering without exposing the prefix in URLs:
+
+```
+content/01.docs/02.getting-started.md  →  _path: '/docs/getting-started'
+content/02.blog/01.index.md            →  _path: '/blog'
+```
+
+Numeric prefixes are removed from every path segment before the usual `index` and date-prefix handling runs.
+
 ### Index files
 
 Files named `index.md` have `/index` stripped from their path:
@@ -341,6 +361,68 @@ export const loader = async () => {
 }
 ```
 
+### Common pattern: catch-all content route
+
+Content-driven apps often use a catch-all page to resolve the current URL to a content document.
+
+```ts
+// app/pages/[...all].ts
+component('page-all', () => {
+  const props = useProps({ all: '' })
+  const ssrData = usePageData<{ doc: ContentItem | null }>()
+  const doc = ref<ContentItem | null>(ssrData?.doc ?? null)
+
+  const contentPath = normalizeContentPath(props.all)
+
+  useHead({
+    title: doc.value?.title ?? 'Not found',
+    meta: doc.value?.description
+      ? [{ name: 'description', content: doc.value.description }]
+      : [],
+  })
+
+  useOnConnected(async () => {
+    if (ssrData) return
+    doc.value = await queryContent(contentPath).first()
+  })
+
+  return html`
+    <article class="prose">
+      ${
+        !doc.value
+          ? html`
+              <h1>404</h1>
+              <p>No content found for <code>${contentPath}</code>.</p>
+            `
+          : doc.value._type === 'json'
+            ? html`
+                <h1>${doc.value.title ?? contentPath}</h1>
+                <pre>${doc.value.body}</pre>
+              `
+            : html`
+                <h1>${doc.value.title ?? contentPath}</h1>
+                ${doc.value.description ? html`<p>${doc.value.description}</p>` : ''}
+                ${unsafeHTML(doc.value.body)}
+              `
+      }
+    </article>
+  `
+})
+
+export const loader = async ({ params }) => {
+  const contentPath = normalizeContentPath(params.all)
+  const doc = await queryContent(contentPath).first()
+  return { doc }
+}
+
+function normalizeContentPath(all: string | undefined) {
+  const slug = String(all ?? '').replace(/^\/+|\/+$/g, '')
+  return slug ? `/${slug}` : '/'
+}
+```
+
+This pattern works well for documentation sites, blogs, and other apps where the route structure mirrors the `content/` directory. `queryContent('/docs/getting-started').first()` returns the full `ContentItem`, including `body`, `excerpt`, and `toc`.
+
 ---
 
 ## `useContentSearch()`

package/e2e/cypress/e2e/content.cy.ts

@@ -5,6 +5,7 @@
  *   /content-index    — queryContent().find()  (all content)
  *   /content-blog     — queryContent('/blog').find() (blog prefix, draft exclusion)
  *   /content-doc      — queryContent('/docs/getting-started').first() (body + TOC)
+ *   /content-guides   — queryContent('/guides').find() (numeric dir/file prefixes)
  *   /content-search   — useContentSearch() (MiniSearch, client-side)
  *   /content-fallback — title/description derived from body when frontmatter omits them
  */
@@ -157,6 +158,42 @@ describe('Content doc — queryContent("/docs/getting-started").first()', () =>
   })
 })
 
+// ─── /content-guides ─────────────────────────────────────────────────────────
+
+describe('Content guides — numeric directory and file prefixes', () => {
+  if (mode !== 'spa') {
+    it('pre-renders stripped guide paths and titles in initial HTML (SSR/SSG)', () => {
+      cy.request('/content-guides').then((response) => {
+        expect(response.body).to.include('Guides Home')
+        expect(response.body).to.include('Intro Guide')
+        expect(response.body).to.include('Advanced Guide')
+        expect(response.body).to.include('data-path="/guides"')
+        expect(response.body).to.include('data-path="/guides/intro"')
+        expect(response.body).to.include('data-path="/guides/advanced"')
+        expect(response.body).not.to.include('01.guides')
+        expect(response.body).not.to.include('/guides/02.intro')
+      })
+    })
+  }
+
+  it('renders guide items after hydration with stripped public paths', () => {
+    cy.visit('/content-guides')
+    cy.get('[data-cy=content-guides-item]', { timeout: 8000 }).should('have.length', 3)
+    cy.get('[data-cy=content-guides-item]').then(($items) => {
+      const paths = [...$items].map((el) => el.getAttribute('data-path'))
+      expect(paths).to.deep.equal(['/guides', '/guides/intro', '/guides/advanced'])
+    })
+  })
+
+  it('preserves numeric file ordering in queryContent results', () => {
+    cy.visit('/content-guides')
+    cy.get('[data-cy=content-guides-title]', { timeout: 8000 }).then(($titles) => {
+      const titles = [...$titles].map((el) => el.textContent?.trim())
+      expect(titles).to.deep.equal(['Guides Home', 'Intro Guide', 'Advanced Guide'])
+    })
+  })
+})
+
 // ─── /content-search ──────────────────────────────────────────────────────────
 
 // Helper: set the search input value and fire the input event.

package/e2e/kitchen-sink/app/pages/content-guides.ts

@@ -0,0 +1,35 @@
+/**
+ * Content guides listing page — exercises numeric directory/file prefixes in
+ * the content layer using `queryContent('/guides').find()`.
+ * Route: /content-guides
+ */
+
+component('page-content-guides', () => {
+  useHead({ title: 'Content Guides — Kitchen Sink' })
+
+  const ssrData = usePageData<{ guides: ContentMeta[] }>()
+  const guides = ref<ContentMeta[]>(ssrData?.guides ?? [])
+
+  useOnConnected(async () => {
+    if (ssrData) return
+    guides.value = await queryContent('/guides').find()
+  })
+
+  return html`
+    <div>
+      <h1 data-cy="content-guides-heading">Guides</h1>
+      <ul data-cy="content-guides-list">
+        ${guides.value.map((guide, index) => html`
+          <li data-cy="content-guides-item" data-path="${guide._path}" data-index="${index}">
+            <strong data-cy="content-guides-title">${guide.title ?? guide._path}</strong>
+          </li>
+        `)}
+      </ul>
+    </div>
+  `
+})
+
+export const loader = async () => {
+  const guides = await queryContent('/guides').find()
+  return { guides }
+}

package/e2e/kitchen-sink/content/01.guides/01.index.md

@@ -0,0 +1,8 @@
+---
+title: Guides Home
+description: Landing page for the guides section.
+---
+
+# Guides Home
+
+Welcome to the ordered guides section.

package/e2e/kitchen-sink/content/01.guides/02.intro.md

@@ -0,0 +1,8 @@
+---
+title: Intro Guide
+description: The first ordered guide.
+---
+
+# Intro Guide
+
+This guide should appear before the advanced guide.

package/e2e/kitchen-sink/content/01.guides/10.advanced.md

@@ -0,0 +1,8 @@
+---
+title: Advanced Guide
+description: The later ordered guide.
+---
+
+# Advanced Guide
+
+This guide should appear after the intro guide.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.20.5",
+  "version": "0.21.0",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [

package/src/__tests__/plugin/content/path-utils.test.ts

@@ -10,18 +10,34 @@ describe('fileToContentPath', () => {
     expect(fileToContentPath(`${DIR}/index.md`, DIR)).toBe('/')
   })
 
+  it('strips numeric prefix from a root-level file segment', () => {
+    expect(fileToContentPath(`${DIR}/01.about.md`, DIR)).toBe('/about')
+  })
+
   it('maps about.md to /about', () => {
     expect(fileToContentPath(`${DIR}/about.md`, DIR)).toBe('/about')
   })
 
+  it('strips numeric prefixes from directory segments', () => {
+    expect(fileToContentPath(`${DIR}/01.docs/02.getting-started.md`, DIR)).toBe('/docs/getting-started')
+  })
+
   it('maps blog/index.md to /blog', () => {
     expect(fileToContentPath(`${DIR}/blog/index.md`, DIR)).toBe('/blog')
   })
 
+  it('strips numeric prefix before handling index files', () => {
+    expect(fileToContentPath(`${DIR}/01.blog/02.index.md`, DIR)).toBe('/blog')
+  })
+
   it('maps blog/2026-04-03-hello.md to /blog/hello (strips date prefix)', () => {
     expect(fileToContentPath(`${DIR}/blog/2026-04-03-hello.md`, DIR)).toBe('/blog/hello')
   })
 
+  it('strips numeric prefix before date prefix on the final segment', () => {
+    expect(fileToContentPath(`${DIR}/blog/01.2026-04-03-hello.md`, DIR)).toBe('/blog/hello')
+  })
+
   it('maps docs/getting-started.md to /docs/getting-started', () => {
     expect(fileToContentPath(`${DIR}/docs/getting-started.md`, DIR)).toBe('/docs/getting-started')
   })

package/src/plugin/content/path-utils.ts

@@ -1,17 +1,24 @@
 import { relative } from 'pathe'
 
+function stripNumericPrefix(segment: string): string {
+  return segment.replace(/^\d+\./, '')
+}
+
 /**
  * Maps a content file path to a `_path` URL path.
  *
  * Rules:
  * - Strip the content dir prefix
  * - Strip the file extension
+ * - Strip `NN.` numeric ordering prefixes from all path segments
  * - Strip `/index` suffix (so blog/index.md → /blog)
  * - Strip `YYYY-MM-DD-` date prefix from the final slug segment
  *
  * Examples:
  *   index.md                → /
+ *   01.about.md             → /about
  *   about.md                → /about
+ *   01.blog/02.hello.md     → /blog/hello
  *   blog/index.md           → /blog
  *   blog/2026-04-03-hello.md → /blog/hello
  *   docs/getting-started.md  → /docs/getting-started
@@ -23,9 +30,10 @@ export function fileToContentPath(filePath: string, contentDir: string): string
   rel = rel.replace(/\.(md|json)$/, '')
 
   // Split into segments
-  const segments = rel.split('/')
+  const segments = rel.split('/').map(stripNumericPrefix)
 
-  // Strip date prefix (YYYY-MM-DD-) from the last segment
+  // Strip date prefix (YYYY-MM-DD-) from the last segment after removing any
+  // numeric ordering prefix (for example 01.2026-04-03-hello.md → /hello).
   const last = segments[segments.length - 1]
   const stripped = last.replace(/^\d{4}-\d{2}-\d{2}-/, '')
   segments[segments.length - 1] = stripped