Add support for page.md

Docs

Author: bcomnes

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node --test:*)"
+    ]
+  }
+}

README.md

@@ -70,12 +70,12 @@ A `src` directory tree might look something like this:
 src % tree
 .
 ├── md-page
-│        ├── README.md # directories with README.md in them turn into /md-page/index.html.
+│        ├── page.md # page.md (or README.md) in a directory turns into /md-page/index.html. page.md takes precedence.
 │        ├── client.ts # Every page can define its own client.ts script that loads only with it.
 │        ├── style.css # Every page can define its own style.css style that loads only with it.
 │        ├── loose-md-page.md # loose markdown get built in place, but lacks some page features.
 │        └── nested-page # pages are built in place and can nest.
-│               ├── README.md # This page is accessed at /md-page/nested-page/.
+│               ├── README.md # This page is accessed at /md-page/nested-page/. (page.md works here too)
 │               ├── style.css # nested pages are just pages, so they also can have a page scoped client and style.
 │               └── client.js # Anywhere JS loads, you can use .js or .ts
 ├── html-page
@@ -109,7 +109,7 @@ src % tree
 │        ├── global.vars.ts # site wide variables get defined in global.vars.ts
 │        ├── markdown-it.settings.ts # You can customize the markdown-it instance used to render markdown
 │        └── esbuild.settings.ts # You can even customize the build settings passed to esbuild
-├── README.md # This is just a top level page built from a README.md file.
+├── page.md # The top level page can also be a page.md (or README.md) file.
 ├── client.ts # the top level page can define a page scoped js client.
 ├── style.css # the top level page can define a page scoped css style.
 └── favicon-16x16.png # static assets can live anywhere. Anything other than JS, CSS and HTML get copied over automatically.
@@ -165,13 +165,15 @@ Because pages are just directories, they nest and structure naturally as a files
 A `md` page looks like this on the filesystem:
 
 ```bash
+src/page-name/page.md
+# or
 src/page-name/README.md
 # or
 src/page-name/loose-md.md
 ```
 
-- `md` pages have two types: a `README.md` in a folder, or a loose `whatever-name-you-want.md` file.
-- `README.md` files transform to an `index.html` at the same path, and `whatever-name-you-want.md` loose markdown files transform into `whatever-name-you-want.html` files at the same path in the `dest` directory.
+- `md` pages have three types: a `page.md`, a `README.md`, or a loose `whatever-name-you-want.md` file.
+- `page.md` and `README.md` files transform to an `index.html` at the same path. When both exist in the same directory, `page.md` takes precedence over `README.md`. `whatever-name-you-want.md` loose markdown files transform into `whatever-name-you-want.html` files at the same path in the `dest` directory.
 - `md` pages can have YAML frontmatter, with variables that are accessible to the page layout and handlebars template blocks when building.
 - You can include html in markdown files, so long as you adhere to the allowable markdown syntax around html tags.
 - `md` pages support [handlebars][hb] template placeholders.
@@ -1250,7 +1252,7 @@ const layout: LayoutFunction<{site: string}, VDOMNode, string> = ({ children })
 - Standardized entrypoints. Every page in a `domstack` site has a natural and obvious entrypoint. There is no magic redirection to learn about.
 - Pages build into `index.html` files inside of named directories. This allows for naturally colocated assets next to the page, pretty URLs and full support for relative URLs.
 - No parallel directory structures. You should never be forced to have two directories with identical layouts to put files next to each other. Everything should be colocatable.
-- Markdown entrypoints are named README.md. This allows for the `src` folder to be fully navigable in GitHub and other git repo hosting providing a natural hosted CMS UI.
+- Markdown entrypoints are named `page.md` or `README.md`. `README.md` allows for the `src` folder to be fully navigable in GitHub and other git repo hosting providing a natural hosted CMS UI. `page.md` is preferred when GitHub navigability is not a concern.
 - Real TC39 ESM from the start.
 - Garbage in, garbage out. Don't over-correct bad input.
 - Conventions + standards. Vanilla file types. No new file extensions. No weird syntax to learn. Language tools should just work because you aren't doing anything weird or out of band.
@@ -1485,6 +1487,7 @@ Some notable features are included below, see the [roadmap](https://github.com/u
 - [x] Rename to domstack
 - [x] markdown-it.settings.ts support
 - [x] page-worker.worker.ts page worker support
+- [x] `page.md` page support
 - ...[See roadmap](https://github.com/users/bcomnes/projects/3/)
 
 ## History

lib/build-pages/page-builders/md/get-md.js

@@ -1,5 +1,3 @@
-/**
- */
 import markdownIt from 'markdown-it'
 import markdownItFootnote from 'markdown-it-footnote'
 import markdownItHighlightjs from 'markdown-it-highlightjs'
@@ -114,11 +112,11 @@ function rewriteLinks (body /*, pretty */) {
   return body.replace(regex, function (_match, p1, p2, _p3) {
     const f = p2.toLowerCase()
 
-    // root readme
-    if (f === 'readme') return p1 + '/"'
+    // root readme or page.md
+    if (f === 'readme' || f === 'page') return p1 + '/"'
 
-    // nested readme
-    if (f.match(/readme$/)) return p1 + f.replace(/readme$/, '') + '"'
+    // nested readme or page.md
+    if (f.match(/readme$/) || f.match(/\/page$/)) return p1 + f.replace(/(readme|page)$/, '') + '"'
 
     // pretty url
     // if (pretty) return p1 + f + '/"'

lib/helpers/dom-stack-warning.js

@@ -10,7 +10,8 @@
  *  'DOM_STACK_WARNING_DUPLICATE_GLOBAL_CLIENT' |
  *  'DOM_STACK_WARNING_DUPLICATE_ESBUILD_SETTINGS' |
  *  'DOM_STACK_WARNING_DUPLICATE_MARKDOWN_IT_SETTINGS' |
- * 'DOM_STACK_WARNING_DUPLICATE_GLOBAL_VARS'
+ *  'DOM_STACK_WARNING_DUPLICATE_GLOBAL_VARS' |
+ *  'DOM_STACK_WARNING_PAGE_MD_SHADOWS_README'
  *  } DomStackWarningCode
  */
 

lib/identify-pages.js

@@ -240,6 +240,11 @@ export async function identifyPages (src, opts = {}) {
       : files['page.html']
     if (htmlPage) htmlPage.type = 'html'
     /** @type {PageFile | undefined} */
+    const pageMd = opts?.buildDrafts
+      ? files['page.md'] ?? files['page.draft.md']
+      : files['page.md']
+    if (pageMd) pageMd.type = 'md'
+    /** @type {PageFile | undefined} */
     const readmePage = opts?.buildDrafts
       ? files['README.md'] ?? files['README.draft.md']
       : files['README.md']
@@ -279,9 +284,16 @@ export async function identifyPages (src, opts = {}) {
       errors.push(err)
     }
 
+    if (pageMd && readmePage) {
+      warnings.push({
+        code: 'DOM_STACK_WARNING_PAGE_MD_SHADOWS_README',
+        message: `${join(dir, 'page.md')} takes precedence over ${join(dir, 'README.md')}. Remove one to silence this warning.`,
+      })
+    }
+
     const page = (conflict)
       ? null
-      : jsPage || htmlPage || readmePage
+      : jsPage || htmlPage || pageMd || readmePage
 
     if (page && page.type) {
       pages.push({
@@ -306,9 +318,10 @@ export async function identifyPages (src, opts = {}) {
       const isMarkdownFile = fileName.endsWith('.md')
       const isDraftFile = fileName.endsWith('.draft.md')
       const isReadmeFile = fileName === 'README.md' || fileName === 'README.draft.md'
+      const isPageMdFile = fileName === 'page.md' || fileName === 'page.draft.md'
 
       if (
-        !isReadmeFile && (
+        !isReadmeFile && !isPageMdFile && (
           (opts.buildDrafts && (isMarkdownFile || isDraftFile)) ||
           (!opts.buildDrafts && (isMarkdownFile && !isDraftFile))
         )

lib/identify-pages.test.js

@@ -15,12 +15,16 @@ test.describe('identify-pages', () => {
     assert.ok(results.layouts, 'Layouts are found')
 
     assert.ok(results.layouts['root'], 'A root layouts is found')
-    assert.equal(Object.keys(results.pages).length, 25, '25 pages are found')
+    assert.equal(Object.keys(results.pages).length, 27, '27 pages are found')
 
-    assert.equal(results.warnings.length, 0, '0 warnings produced')
+    assert.equal(results.warnings.length, 1, '1 warning produced')
+    assert.equal(results.warnings[0].code, 'DOM_STACK_WARNING_PAGE_MD_SHADOWS_README', 'page.md shadows README.md warning is produced')
     // assert.equal(results.nonPageFolders.length, 4, '4 non-page-folder')
     assert.equal(results.pages.find(p => p.path === 'html-page')?.pageFile?.type, 'html', 'html page is type html')
     assert.equal(results.pages.find(p => p.path === 'md-page')?.pageFile?.type, 'md', 'md page is type md')
     assert.equal(results.pages.find(p => p.path === 'js-page')?.pageFile?.type, 'js', 'js-page is type js')
+    assert.equal(results.pages.find(p => p.path === 'page-md-page')?.pageFile?.type, 'md', 'page-md-page is type md')
+    assert.equal(results.pages.find(p => p.path === 'page-md-page')?.pageFile?.basename, 'page.md', 'page-md-page uses page.md')
+    assert.equal(results.pages.find(p => p.path === 'page-md-precedence')?.pageFile?.basename, 'page.md', 'page.md takes precedence over README.md')
   })
 })

test-cases/general-features/index.test.js

@@ -74,6 +74,14 @@ test.describe('general-features', () => {
         style: true,
         worker: true
       },
+      'page-md-page/index.html': {
+        client: false,
+        style: false,
+      },
+      'page-md-precedence/index.html': {
+        client: false,
+        style: false,
+      },
     }
 
     const files = await allFiles(dest, { shaper: fwData => fwData })
@@ -90,6 +98,17 @@ test.describe('general-features', () => {
             ? 'Generated'
             : 'Did not generate'} a global client`)
 
+    // Special test for page.md precedence over README.md
+    const pageMdPrecedencePath = path.join(dest, 'page-md-precedence/index.html')
+    try {
+      const pageMdContent = await readFile(pageMdPrecedencePath, 'utf8')
+      assert.ok(pageMdContent.includes('from page.md'), 'page.md content is rendered')
+      assert.ok(!pageMdContent.includes('from README.md'), 'README.md content is not rendered when page.md exists')
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Unknown error', { cause: err })
+      assert.fail('Failed to verify page.md precedence: ' + error.message)
+    }
+
     // Special test for markdown-it.settings.js
     const mdSettingsTestPath = path.join(dest, 'md-page/markdown-settings-test.html')
     try {

test-cases/general-features/src/page-md-page/page.md

@@ -0,0 +1,3 @@
+# page-md-page
+
+This is an md page rendered from a page.md file.

test-cases/general-features/src/page-md-precedence/README.md

@@ -0,0 +1,3 @@
+# page-md-precedence (from README.md)
+
+This content should NOT appear - page.md takes precedence.

test-cases/general-features/src/page-md-precedence/page.md

@@ -0,0 +1,3 @@
+# page-md-precedence (from page.md)
+
+This content comes from page.md and should take precedence over README.md.