orga-build 0.8.0 → 0.10.0

package/README.org

@@ -4,7 +4,9 @@ A simple tool that builds org-mode files into a website.
 
 * Architecture
 
-orga-build is built on top of Vite with a Vite-native architecture. The dev server uses Vite's native =createServer().listen()= pattern (no custom Express wrapper), which ensures maximum compatibility with the Vite ecosystem, including plugins like Cloudflare Workers.
+orga-build is built on top of Vite (8+) with a Vite-native architecture. The dev server uses Vite's native =createServer().listen()= pattern (no custom Express wrapper), which ensures maximum compatibility with the Vite ecosystem, including plugins like Cloudflare Workers.
+
+The build uses Vite's Environment API: =orgaBuildPlugin= configures an =ssr= and a =client= environment, and its =buildApp= hook builds both and prerenders every page and endpoint to static HTML. Pages ship no JavaScript unless they use an [[*Interactive Components (Islands)][island]]. The CLI is a thin wrapper, so =vite build= with the plugin produces the same site.
 
 ** Key Design Principles
 
@@ -31,30 +33,26 @@ export default {
 
 Note: Do NOT add =orgaBuildPlugin()= to =vitePlugins= - it's already included by the CLI. Only add external plugins.
 
-For advanced users integrating directly with Vite (without the orga-build CLI), use =orgaBuildPlugin= in your =vite.config.js=:
+For advanced users integrating directly with Vite (without the orga-build CLI), use =orgaBuildPlugin= in your =vite.config.js=. =vite= then serves the site with SSR and =vite build= builds the static site:
 
 #+begin_src javascript
 // vite.config.js (advanced - direct Vite integration)
 import { cloudflare } from '@cloudflare/vite-plugin'
-import { orgaBuildPlugin, alias } from 'orga-build'
+import { orgaBuildPlugin } from 'orga-build'
 
 export default {
   plugins: [
     cloudflare(),
-    ...orgaBuildPlugin({ root: 'pages', containerClass: [] })
-  ],
-  resolve: { alias }
+    ...orgaBuildPlugin({ root: 'pages', outDir: 'out', containerClass: [] })
+  ]
 }
 #+end_src
 
 ** Default HTML Template
 
-If your project doesn't have an =index.html= file, orga-build provides a default template that:
-- Sets up React rendering
-- Enables client-side routing
-- Works in both dev and production builds
+If your project doesn't have an =index.html= file, orga-build provides a default template: a bare HTML document with a =<div id="root">= that pages are rendered into.
 
-To customize the HTML shell, create your own =index.html= in your project root.
+To customize the HTML shell, create your own =index.html= in your project root. Keep =<div id="root"></div>=; Vite processes the rest like any =index.html= (bundling linked scripts and stylesheets), and =%orga.<key>%= placeholders are filled from each page's exports (e.g. =%orga.title%=).
 
 * Installation
 
@@ -62,45 +60,64 @@ To customize the HTML shell, create your own =index.html= in your project root.
 npm install orga-build
 #+end_src
 
+* Usage
+
+#+begin_src bash
+orga-build dev            # dev server with live reload
+orga-build                # build the static site into outDir
+orga-build --outDir dist  # override outDir (also -o)
+#+end_src
+
 * Configuration
 
-orga-build uses =orga.config.js= (or =orga.config.mjs=) as the primary configuration file. This file should be placed in your project root.
+orga-build uses =orga.config.js= (or =orga.config.mjs=) as the primary configuration file. This file should be placed in your project root. It is optional; a config file that fails to load fails the command.
 
 #+begin_src javascript
 // orga.config.js
 export default {
-  // Directory containing your .org files (default: 'pages')
+  // Directory containing your .org files (default: '.', the project root)
   root: 'pages',
 
-  // Output directory for production build (default: 'out')
+  // Output directory for production build (default: '.out')
   outDir: 'out',
 
+  // Absolute URL the site is served from, for canonical URLs, feeds and
+  // sitemaps. Include the path if the site isn't at the domain root.
+  site: 'https://example.com',
+
   // CSS class(es) to wrap rendered org content
   containerClass: ['prose', 'prose-lg'],
 
-  // Global stylesheet URLs (explicit, no magic files)
-  // These are injected in dev SSR <head> and imported by the client entry.
-  styles: ['/style.css'],
+  // Global stylesheets — paths relative to orga.config.js (leading / optional).
+  // Linked from the HTML shell; Vite processes them (with HMR in dev).
+  styles: ['pages/style.css'],
 
   // Extra rehype plugins appended to orga-build defaults
   // Useful for syntax highlighting (e.g. rehype-pretty-code).
   rehypePlugins: [],
 
   // Additional Vite plugins
-  vitePlugins: []
+  vitePlugins: [],
+
+  // Glob patterns (relative to root) to exclude from content scanning.
+  // Useful for generated or declaration files that must live inside root
+  // but should not be treated as pages or endpoints.
+  exclude: ['**/*.d.ts']
 }
 #+end_src
 
 ** Configuration Options
 
-| Option         | Type              | Default | Description                                          |
-|----------------+-------------------+---------+------------------------------------------------------|
-| =root=           | =string=            | ='pages'= | Directory containing content files                   |
-| =outDir=         | =string=            | ='out'=   | Output directory for production build                |
-| =containerClass= | =string \vert string[]= | =[]=      | CSS class(es) for content wrapper                    |
-| =styles=         | =string[]=          | =[]=      | Global stylesheet URLs injected/imported explicitly  |
-| =rehypePlugins=  | =PluggableList=     | =[]=      | Extra rehype plugins appended to orga-build defaults |
-| =vitePlugins=    | =PluginOption[]=    | =[]=      | Additional Vite plugins                              |
+| Option         | Type              | Default | Description                                                     |
+|----------------+-------------------+---------+-----------------------------------------------------------------|
+| =root=           | =string=            | ='.'=     | Directory containing content files                              |
+| =outDir=         | =string=            | ='.out'=  | Output directory for production build                           |
+| =site=           | =string=            | none    | Absolute URL the site is served from, see [[*Site URL][Site URL]]               |
+| =containerClass= | =string \vert string[]= | =[]=      | CSS class(es) for content wrapper                               |
+| =styles=         | =string[]=          | =[]=      | Stylesheets to link; paths relative to =orga.config.js=           |
+| =exclude=        | =string[]=          | =[]=      | Glob patterns (relative to =root=) excluded from content scanning |
+| =rehypePlugins=  | =PluggableList=     | =[]=      | Extra rehype plugins appended to orga-build defaults            |
+| =vitePlugins=    | =PluginOption[]=    | =[]=      | Additional Vite plugins                                         |
 
 ** Syntax Highlighting Example
 
@@ -126,7 +143,7 @@ Page routes are discovered from =.org=, =.tsx=, and =.jsx= files.
 
 At build time, page routes are emitted as HTML:
 
-- =/about= -> =out/about/index.html=
+- =/about= -> =.out/about/index.html=
 
 ** Endpoint Routes
 
@@ -146,13 +163,65 @@ export async function GET(ctx) {
 }
 #+end_src
 
+=ctx= has:
+
+- =url=: the request URL. At build time it is =site + route= (or =http://localhost= + route without =site=).
+- =site=: the configured =site=, see [[*Site URL][Site URL]]
+- =mode=: ='dev'= or ='build'=
+- =route.route=: the route, e.g. ='/rss.xml'=
+
 At build time, endpoint routes are emitted to exact filenames:
 
-- =/rss.xml= -> =out/rss.xml=
-- =/api/data.json= -> =out/api/data.json=
+- =/rss.xml= -> =.out/rss.xml=
+- =/api/data.json= -> =.out/api/data.json=
 
 Route conflicts (same final route path) fail fast during dev/build startup.
 
+** Links
+
+Links to =.org= files point at their pages, under Vite's =base=. Every heading gets an =id=: its =CUSTOM_ID= property when set, otherwise a slug of its text (=* Getting Started= → =#getting-started=).
+
+| Link                                   | Goes to                      |
+|----------------------------------------+------------------------------|
+| =[[file:guide.org]]=                   | =/guide=                     |
+| =[[file:guide.org::*Getting Started]]= | =/guide#getting-started=     |
+| =[[file:guide.org::#install]]=         | =/guide#install=             |
+| =[[*Getting Started]]=                 | heading on the same page     |
+| =[[#install]]=                         | =CUSTOM_ID= on the same page |
+
+A =::*Heading= link to another file assumes that heading's id is the slug of its text. If the heading has a =CUSTOM_ID=, link to it with =::#id= instead. =id:= links aren't supported yet.
+
+* Interactive Components (Islands)
+
+Pages are static HTML. To run a component in the browser, start its module with React's ='use client'= directive, like in any React framework:
+
+#+begin_src tsx
+// _components.tsx
+'use client'
+import { useState } from 'react'
+
+export function Counter({ start }: { start: number }) {
+  const [count, setCount] = useState(start)
+  return <button onClick={() => setCount(count + 1)}>{count}</button>
+}
+#+end_src
+
+#+begin_example
+#+jsx: <Counter start={1} />
+#+end_example
+
+The component is still prerendered. On pages that use it, the browser imports just that module (plus a shared React chunk) and hydrates it in place; every other page ships no JavaScript. Only components become islands, recognized by their PascalCase name (or the default export); hooks and other exports of a ='use client'= module stay plain values. A page file (=.tsx=) can start with ='use client'= too, which makes the whole page an island.
+
+Props cross to the browser as JSON, so they must be serializable: no functions and no =children=. Components rendered /inside/ an island are already client code and have no such limit.
+
+An island is wrapped in an =<orga-island>= element, so it can't sit where HTML allows only specific children, such as directly inside =<table>=, =<tbody>=, =<tr>=, =<select>= or =<ul>=. Make the island the whole table or list instead.
+
+Islands hydrate as soon as the page loads. Pass =client="visible"= to defer hydration until the island scrolls into view, which also defers loading React:
+
+#+begin_example
+#+jsx: <Counter start={1} client="visible" />
+#+end_example
+
 * TypeScript Setup
 
 If you're using TypeScript and want type support for the =orga-build:content= virtual module, you need to add a reference to the type definitions.
@@ -218,9 +287,9 @@ const writing = getPages('writing')
 // Get entries in a nested path
 const posts2025 = getPages('content/writing/2025')
 
-// Filter out drafts
-const published = getPages('writing', (entry) => {
-  return entry.data['draft'] !== 'true'
+// Filter by metadata
+const featured = getPages('writing', (entry) => {
+  return entry.data['featured'] === 'true'
 })
 #+end_src
 
@@ -262,6 +331,10 @@ const entries = getEntries([
 ])
 #+end_src
 
+*** =site=
+
+The configured =site=, without a trailing slash, or =undefined=. See [[*Site URL][Site URL]].
+
 *** Aliases
 
 For Astro familiarity:
@@ -279,7 +352,7 @@ interface ContentEntry {
   path: string                  // e.g., 'writing' or 'content/writing/2025'
   filePath: string              // absolute source file path
   ext: 'org' | 'tsx' | 'jsx'   // file extension
-  data: Record<string, unknown> // metadata from org headers
+  data: Record<string, unknown> // org keywords, or TSX/JSX named exports
 }
 #+end_src
 
@@ -305,7 +378,48 @@ This becomes:
 }
 #+end_src
 
-For =.tsx= and =.jsx= files, the =data= field is currently empty in v1.
+For =.tsx= and =.jsx= files, =data= holds the page's named exports whose values are literals: strings, numbers, booleans, =null=, templates without =${}=, and arrays of those. Other exports (functions, computed values) are skipped, since pages aren't run to read them.
+
+#+begin_src tsx
+export const title = 'About'
+export const date = '2025-01-15'
+export const tags = ['meta', 'site']
+
+export default function About() {
+  return <h1>{title}</h1>
+}
+#+end_src
+
+** Drafts
+
+Mark a page as a draft with =#+draft: t= (or =true=, =yes=), or in a TSX/JSX
+page with =export const draft = true=. The dev server
+serves drafts so you can preview them; the build leaves them out entirely: no
+HTML, and no entry in =getPages=, so feeds, sitemaps, and index pages skip
+them without filtering.
+
+** Site URL
+
+Set =site= in the config to the absolute URL the site is served from. It is
+exported from =orga-build:content= and passed to endpoints as =ctx.site=,
+without a trailing slash, so a page's absolute URL is =site + page.slug=:
+
+#+begin_src tsx
+// _layout.tsx
+import { site } from 'orga-build:content'
+
+export default function Layout({ slug, children }) {
+  const share = 'https://bsky.app/intent/compose?text=' + encodeURIComponent(site + slug)
+  return (
+    <>
+      {children}
+      <a href={share}>Share</a>
+    </>
+  )
+}
+#+end_src
+
+If the site is served under a path, include it: =site: 'https://example.com/blog'=.
 
 ** Path Matching Behavior
 
@@ -332,9 +446,7 @@ Path matching works hierarchically:
 import { getPages } from 'orga-build:content'
 
 export default function BlogIndex() {
-  const posts = getPages('writing', (entry) => {
-    return entry.data['draft'] !== 'true'
-  }).sort((a, b) => {
+  const posts = getPages('writing').sort((a, b) => {
     // Sort by date descending
     return String(b.data['date']).localeCompare(String(a.data['date']))
   })
@@ -384,12 +496,155 @@ export default function Post({ slug }: { slug: string }) {
 }
 #+end_src
 
-* Development
+* Feeds and Sitemaps
+
+There is no built-in feed or sitemap. Write them as [[*Endpoint Routes][endpoints]] built on =getPages=, and adapt them to your site. Both need =site= for absolute URLs. Drafts are already left out of =getPages= in the build.
+
+** RSS Feed
+
+This feed lists the pages under =writing/= that have a =#+date:=, newest first. It reads the =YYYY-MM-DD= part of the date, so both =2025-01-15= and =<2025-01-15 Wed>= work.
+
+#+begin_src ts
+// rss.xml.ts
+import { getPages, site } from 'orga-build:content'
+
+const escape = (value: unknown) =>
+  String(value).replace(/[<>&'"]/g, (c) => `&#${c.charCodeAt(0)};`)
+
+export function GET() {
+  if (!site) throw new Error('Set "site" in orga.config.js to build the feed')
+
+  const posts = getPages('writing')
+    .flatMap((page) => {
+      const date = String(page.data['date'] ?? '').match(/\d{4}-\d{2}-\d{2}/)
+      return date ? [{ page, date: date[0] }] : []
+    })
+    .sort((a, b) => b.date.localeCompare(a.date))
+
+  const items = posts.map(({ page, date }) => {
+    const url = escape(site + page.slug)
+    return `
+    <item>
+      <title>${escape(page.data['title'] ?? page.id)}</title>
+      <link>${url}</link>
+      <guid>${url}</guid>
+      <pubDate>${new Date(date).toUTCString()}</pubDate>
+    </item>`
+  })
+
+  return new Response(
+    `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>My Site</title>
+    <link>${escape(site + '/')}</link>
+    <description>Latest writing</description>${items.join('')}
+  </channel>
+</rss>
+`,
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } }
+  )
+}
+#+end_src
+
+Feed readers look for the feed in the page's =<head>=. Layouts render inside =<body>=, so add the link to the =<head>= of your own [[*Default HTML Template][index.html]] instead, with the feed's full URL (=site= + =/rss.xml=):
+
+#+begin_src html
+<link rel="alternate" type="application/rss+xml" href="https://example.com/rss.xml" />
+#+end_src
+
+** Sitemap
+
+#+begin_src ts
+// sitemap.xml.ts
+import { getPages, site } from 'orga-build:content'
+
+const escape = (value: unknown) =>
+  String(value).replace(/[<>&'"]/g, (c) => `&#${c.charCodeAt(0)};`)
+
+export function GET() {
+  if (!site) throw new Error('Set "site" in orga.config.js to build the sitemap')
+
+  const urls = getPages().map(
+    (page) => `
+  <url><loc>${escape(site + page.slug)}</loc></url>`
+  )
+
+  return new Response(
+    `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">${urls.join('')}
+</urlset>
+`,
+    { headers: { 'content-type': 'application/xml; charset=utf-8' } }
+  )
+}
+#+end_src
+
+** robots.txt
+
+A small endpoint, which can also point crawlers at the sitemap:
+
+#+begin_src ts
+// robots.txt.ts
+import { site } from 'orga-build:content'
+
+export function GET() {
+  if (!site) throw new Error('Set "site" in orga.config.js to build robots.txt')
+  return new Response(`User-agent: *\nAllow: /\nSitemap: ${site}/sitemap.xml\n`)
+}
+#+end_src
+
+* Search with Pagefind
+
+The build output is plain static HTML, so [[https://pagefind.app][Pagefind]] can index it without any orga-build integration. Install it and run it on =outDir= (default =.out=) after each build:
+
+#+begin_src bash
+npm install -D pagefind
+#+end_src
+
+#+begin_src json
+{
+  "scripts": {
+    "build": "orga-build && pagefind --site .out"
+  }
+}
+#+end_src
+
+Pagefind writes its index and UI to =.out/pagefind/=. Pagefind already skips =<nav>= and =<footer>= elements. To also leave out headers, sidebars and other page chrome, mark the content area with =data-pagefind-body= in your root =_layout.jsx=, and Pagefind indexes only that. Then add the search UI from the same layout. It is made of web components, so it doesn't need an island:
+
+#+begin_src jsx
+// pages/_layout.jsx
+export default function Layout({ children }) {
+  return (
+    <>
+      <header>
+        <pagefind-modal-trigger></pagefind-modal-trigger>
+        <pagefind-modal></pagefind-modal>
+      </header>
+      <main data-pagefind-body>{children}</main>
+      <link href="/pagefind/pagefind-component-ui.css" rel="stylesheet" />
+      <script src="/pagefind/pagefind-component-ui.js" type="module"></script>
+    </>
+  )
+}
+#+end_src
+
+Pages without =data-pagefind-body= are left out of the index, so put it in a layout that wraps every page you want searchable.
+
+The index only exists after a build, so search doesn't work in =orga-build dev=. To try it locally, run =npx pagefind --site .out --serve= after building.
 
-** TODO Items
+In a =_layout.tsx=, declare the elements so TypeScript accepts them:
 
-- resolve relative path in links and images
-- monitor file changes and cache properly
+#+begin_src tsx
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'pagefind-modal-trigger': React.HTMLAttributes<HTMLElement>
+      'pagefind-modal': React.HTMLAttributes<HTMLElement>
+    }
+  }
+}
+#+end_src
 
 * License
 

package/cli.js

@@ -1,18 +1,17 @@
 #!/usr/bin/env node
 
+import path from 'node:path'
 import { argv } from 'node:process'
 import { parseArgs } from 'node:util'
 import { build } from './lib/build.js'
 import { loadConfig } from './lib/config.js'
 import { serve } from './lib/serve.js'
 
-const { positionals } = parseArgs({
+const { values, positionals } = parseArgs({
 	args: argv.slice(2),
 	options: {
-		watch: { type: 'boolean', short: 'w' },
-		outDir: { type: 'string', short: 'o', default: '.out' }
+		outDir: { type: 'string', short: 'o' }
 	},
-	tokens: true,
 	allowPositionals: true
 })
 
@@ -20,6 +19,7 @@ const { config, projectRoot } = await loadConfig(
 	'orga.config.js',
 	'orga.config.mjs'
 )
+if (values.outDir) config.outDir = path.resolve(values.outDir)
 
 await (positionals.includes('dev')
 	? serve(config, 3000, projectRoot)