orga-build 0.2.7 → 0.3.1

package/README.org

@@ -0,0 +1,251 @@
+#+TITLE: orga-build
+
+A simple tool that builds org-mode files into a website.
+
+* Installation
+
+#+begin_src bash
+npm install orga-build
+#+end_src
+
+* 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.
+
+** Minimal Setup
+
+1. Create a =types.d.ts= file in your project root (or any location):
+
+#+begin_src typescript
+/// <reference types="orga-build/client" />
+#+end_src
+
+2. Ensure your =tsconfig.json= includes this file:
+
+#+begin_src json
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx"
+  },
+  "include": ["types.d.ts", "**/*"]
+}
+#+end_src
+
+That's it! TypeScript will now recognize imports from =orga-build:content=.
+
+** Why This is Needed
+
+The =orga-build:content= module is a "virtual module" - it doesn't exist as a physical file but is generated at build time by Vite. The =/// <reference types="orga-build/client" />= directive tells TypeScript to load the type definitions for this virtual module.
+
+* Content Query API
+
+orga-build provides an Astro-inspired content query API via the =orga-build:content= virtual module. This allows you to safely query content entries from any page or layout without circular imports.
+
+** Importing
+
+#+begin_src typescript
+import { getPages, getPage } from 'orga-build:content'
+#+end_src
+
+** API Reference
+
+*** =getPages(path?, filter?)=
+
+Get all content entries matching a path pattern.
+
+*Parameters:*
+- =path= (optional): Path prefix to filter by (e.g., ='writing'=, ='content/writing/2025'=)
+- =filter= (optional): Filter function to further refine results
+
+*Returns:* Array of =ContentEntry= objects
+
+*Examples:*
+
+#+begin_src typescript
+// Get all entries
+const all = getPages()
+
+// Get all entries in the 'writing' path
+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'
+})
+#+end_src
+
+*** =getPage(idOrSlug, path?)=
+
+Get a single content entry by id or slug.
+
+*Parameters:*
+- =idOrSlug=: The id or slug of the entry to find
+- =path= (optional): Path prefix to search within
+
+*Returns:* =ContentEntry | undefined=
+
+*Examples:*
+
+#+begin_src typescript
+// Get by slug
+const post = getPage('/writing/the-birth-of-emacsclient')
+
+// Get by id within a path
+const post = getPage('the-birth-of-emacsclient', 'writing')
+#+end_src
+
+*** =getEntries(refs)=
+
+Get multiple content entries by reference.
+
+*Parameters:*
+- =refs=: Array of references with =id= and optional =path=
+
+*Returns:* Array of =ContentEntry | undefined=
+
+*Examples:*
+
+#+begin_src typescript
+const entries = getEntries([
+  { id: 'post-1', path: 'writing' },
+  { id: 'post-2', path: 'writing' }
+])
+#+end_src
+
+*** Aliases
+
+For Astro familiarity:
+- =getCollection= - Alias for =getPages=
+- =getEntry= - Alias for =getPage=
+
+** ContentEntry Type
+
+Each entry has the following structure:
+
+#+begin_src typescript
+interface ContentEntry {
+  id: string                    // e.g., 'post-name' or 'index'
+  slug: string                  // e.g., '/writing/post-name'
+  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
+}
+#+end_src
+
+** Metadata Extraction
+
+For =.org= files, orga-build automatically extracts metadata from org-mode headers:
+
+#+begin_example
+#+title: My Post
+#+date: 2025-01-15
+#+draft: false
+#+end_example
+
+This becomes:
+
+#+begin_src typescript
+{
+  data: {
+    title: 'My Post',
+    date: '2025-01-15',
+    draft: 'false'
+  }
+}
+#+end_src
+
+For =.tsx= and =.jsx= files, the =data= field is currently empty in v1.
+
+** Path Matching Behavior
+
+Path matching works hierarchically:
+
+- =getPages()= - Returns all entries
+- =getPages('writing')= - Returns entries where:
+  - =path = 'writing'=, or
+  - =path= starts with ='writing/'=
+- =getPages('content/writing/2025')= - Returns entries under that specific subtree
+
+*Path Derivation Examples:*
+
+| File Path | Slug | Path | ID |
+|-----------+------+------+----|
+| =pages/writing/foo.org= | =/writing/foo= | =writing= | =foo= |
+| =pages/content/writing/2025/post.org= | =/content/writing/2025/post= | =content/writing/2025= | =post= |
+| =pages/index.org= | =/= | =''= (empty) | =index= |
+| =pages/about.org= | =/about= | =''= (empty) | =about= |
+
+** Example: Blog Index Page
+
+#+begin_src tsx
+import { getPages } from 'orga-build:content'
+
+export default function BlogIndex() {
+  const posts = getPages('writing', (entry) => {
+    return entry.data['draft'] !== 'true'
+  }).sort((a, b) => {
+    // Sort by date descending
+    return String(b.data['date']).localeCompare(String(a.data['date']))
+  })
+
+  return (
+    <div>
+      <h1>Blog Posts</h1>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>
+            <a href={post.slug}>{String(post.data['title'])}</a>
+            <span>{String(post.data['date'])}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+#+end_src
+
+** Example: Related Posts
+
+#+begin_src tsx
+import { getPages } from 'orga-build:content'
+
+export default function Post({ slug }: { slug: string }) {
+  // Get current post
+  const currentPost = getPages().find((p) => p.slug === slug)
+
+  // Get related posts from same path
+  const related = getPages(currentPost?.path).filter(
+    (p) => p.slug !== slug
+  ).slice(0, 3)
+
+  return (
+    <div>
+      <h2>Related Posts</h2>
+      <ul>
+        {related.map((post) => (
+          <li key={post.id}>
+            <a href={post.slug}>{String(post.data['title'])}</a>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+#+end_src
+
+* Development
+
+** TODO Items
+
+- resolve relative path in links and images
+- monitor file changes and cache properly
+
+* License
+
+MIT

package/lib/content.d.ts

@@ -0,0 +1,51 @@
+declare module 'orga-build:content' {
+	export interface ContentEntry {
+		id: string
+		slug: string
+		path: string
+		filePath: string
+		ext: 'org' | 'tsx' | 'jsx'
+		data: Record<string, unknown>
+	}
+
+	/**
+	 * Get all content entries matching a path pattern
+	 * @param path - Optional path prefix to filter by (e.g., 'writing', 'content/writing/2025')
+	 * @param filter - Optional filter function to further refine results
+	 * @returns Array of matching content entries
+	 */
+	export function getPages(
+		path?: string,
+		filter?: (entry: ContentEntry) => boolean
+	): ContentEntry[]
+
+	/**
+	 * Get a single content entry by id or slug
+	 * @param idOrSlug - The id or slug of the entry to find
+	 * @param path - Optional path prefix to search within
+	 * @returns The matching content entry or undefined
+	 */
+	export function getPage(
+		idOrSlug: string,
+		path?: string
+	): ContentEntry | undefined
+
+	/**
+	 * Get multiple content entries by reference
+	 * @param refs - Array of references with id and optional path
+	 * @returns Array of matching content entries (may include undefined)
+	 */
+	export function getEntries(
+		refs: Array<{ path?: string; id: string }>
+	): Array<ContentEntry | undefined>
+
+	/**
+	 * Alias for getPages
+	 */
+	export const getCollection: typeof getPages
+
+	/**
+	 * Alias for getPage
+	 */
+	export const getEntry: typeof getPage
+}

package/lib/files.d.ts

@@ -1,9 +1,3 @@
-/**
- * @typedef {Object} Page
- * @property {string} dataPath
- * @property {string} [title]
- *   Path to the page data file
- */
 /**
  * @param {string} dir
  */
@@ -12,6 +6,7 @@ export function setup(dir: string): {
     page: (id: string) => Promise<Page>;
     components: () => Promise<string | null>;
     layouts: () => Promise<Record<string, string>>;
+    contentEntries: () => Promise<ContentEntry[]>;
 };
 export type Page = {
     dataPath: string;
@@ -20,4 +15,12 @@ export type Page = {
      */
     title?: string;
 };
+export type ContentEntry = {
+    id: string;
+    slug: string;
+    path: string;
+    filePath: string;
+    ext: "org" | "tsx" | "jsx";
+    data: Record<string, unknown>;
+};
 //# sourceMappingURL=files.d.ts.map

package/lib/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;GAEG;AACH,2BAFW,MAAM;;eA4EJ,MAAM;;;EAKlB;;cAvFa,MAAM;;;;YACN,MAAM"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["files.js"],"names":[],"mappings":"AA8EA;;GAEG;AACH,2BAFW,MAAM;;eA2HJ,MAAM;;;;EAKlB;;cAxMa,MAAM;;;;YACN,MAAM;;;QAMN,MAAM;UACN,MAAM;UACN,MAAM;cACN,MAAM;SACN,KAAK,GAAG,KAAK,GAAG,KAAK;UACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC"}

package/lib/files.js

@@ -1,5 +1,7 @@
 import { globby } from 'globby'
 import path from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { getSettings } from 'orga'
 
 /**
  * @typedef {Object} Page
@@ -8,6 +10,72 @@ import path from 'node:path'
  *   Path to the page data file
  */
 
+/**
+ * @typedef {Object} ContentEntry
+ * @property {string} id
+ * @property {string} slug
+ * @property {string} path
+ * @property {string} filePath
+ * @property {'org' | 'tsx' | 'jsx'} ext
+ * @property {Record<string, unknown>} data
+ */
+
+/**
+ * Extract file extension from file path
+ * @param {string} filePath
+ * @returns {'org' | 'tsx' | 'jsx'}
+ */
+function getFileExtension(filePath) {
+	const match = filePath.match(/\.(org|tsx|jsx)$/)
+	return /** @type {'org' | 'tsx' | 'jsx'} */ (match ? match[1] : 'org')
+}
+
+/**
+ * Derive content path from slug
+ * @param {string} slug - e.g. '/writing/foo', '/content/writing/2025/post', '/'
+ * @returns {string} - e.g. 'writing', 'content/writing/2025', ''
+ */
+function getContentPath(slug) {
+	// Remove leading slash
+	let normalized = slug.replace(/^\/+/, '')
+	// Remove trailing slash
+	normalized = normalized.replace(/\/+$/, '')
+
+	// If root page, return empty string
+	if (!normalized) {
+		return ''
+	}
+
+	// Get all segments except the last one (the file name)
+	const segments = normalized.split('/')
+	if (segments.length === 1) {
+		// Single segment like '/about' -> path is empty (root level)
+		return ''
+	}
+
+	// Multiple segments like '/writing/foo' -> path is 'writing'
+	return segments.slice(0, -1).join('/')
+}
+
+/**
+ * Derive content id from slug
+ * @param {string} slug - e.g. '/writing/foo', '/writing', '/'
+ * @returns {string} - e.g. 'foo', 'writing', 'index'
+ */
+function getContentId(slug) {
+	// Remove leading and trailing slashes
+	let normalized = slug.replace(/^\/+/, '').replace(/\/+$/, '')
+
+	// If root page, return 'index'
+	if (!normalized) {
+		return 'index'
+	}
+
+	// Get last segment
+	const segments = normalized.split('/')
+	return segments[segments.length - 1] || 'index'
+}
+
 /**
  * @param {string} dir
  */
@@ -78,13 +146,60 @@ export function setup(dir) {
 		return files[0] ? path.join(dir, files[0]) : null
 	})
 
-	return {
+	const contentEntries = cache(async function () {
+		const allPages = await pages()
+		/** @type {ContentEntry[]} */
+		const entries = []
+
+		for (const [slug, pageData] of Object.entries(allPages)) {
+			const filePath = pageData.dataPath
+			const ext = getFileExtension(filePath)
+
+			// Derive path from directory structure
+			const derivedPath = getContentPath(slug)
+
+			// Derive id from the slug (last segment or 'index')
+			const id = getContentId(slug)
+
+			/** @type {Record<string, unknown>} */
+			let data = {}
+
+			// Extract metadata from .org files
+			if (ext === 'org') {
+				try {
+					const content = await readFile(filePath, 'utf-8')
+					data = getSettings(content)
+				} catch (/** @type {any} */ error) {
+					console.warn(
+						`Failed to read metadata from ${filePath}:`,
+						error?.message || error
+					)
+				}
+			}
+
+			entries.push({
+				id,
+				slug,
+				path: derivedPath,
+				filePath,
+				ext,
+				data
+			})
+		}
+
+		return entries
+	})
+
+	const files = {
 		pages,
 		page,
 		components,
-		layouts
+		layouts,
+		contentEntries
 	}
 
+	return files
+
 	/** @param {string} id */
 	async function page(id) {
 		const all = await pages()

package/lib/vite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["vite.js"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,uCAHG;IAAwB,GAAG,EAAnB,MAAM;CACd,GAAU,OAAO,MAAM,EAAE,MAAM,CA2GjC"}
+{"version":3,"file":"vite.d.ts","sourceRoot":"","sources":["vite.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,uCAHG;IAAwB,GAAG,EAAnB,MAAM;CACd,GAAU,OAAO,MAAM,EAAE,MAAM,CA6JjC"}

package/lib/vite.js

@@ -4,6 +4,8 @@ import path from 'node:path'
 const magicModulePrefix = '/@orga-build/'
 const pagesModuleId = magicModulePrefix + 'pages'
 const appEntryId = `${magicModulePrefix}main.js`
+const contentModuleId = 'orga-build:content'
+const contentModuleIdResolved = '\0' + contentModuleId
 
 /**
  * @param {Object} options
@@ -39,6 +41,11 @@ export function pluginFactory({ dir }) {
 			}
 
 			reloadVirtualModule('/')
+
+			// Invalidate content module on file changes
+			watcher.on('change', () => {
+				reloadVirtualModule(contentModuleIdResolved)
+			})
 		},
 
 		buildStart() {},
@@ -47,6 +54,9 @@ export function pluginFactory({ dir }) {
 			if (id === appEntryId) {
 				return appEntryId
 			}
+			if (id === contentModuleId) {
+				return contentModuleIdResolved
+			}
 			if (id.startsWith(magicModulePrefix)) {
 				return id
 			}
@@ -55,6 +65,9 @@ export function pluginFactory({ dir }) {
 			if (id === appEntryId) {
 				return `import "orga-build/csr";`
 			}
+			if (id === contentModuleIdResolved) {
+				return await renderContentModule()
+			}
 			if (id === pagesModuleId) {
 				return await renderPageList()
 			}
@@ -115,4 +128,43 @@ export default pages;
 		}
 		return ''
 	}
+
+	async function renderContentModule() {
+		const entries = await files.contentEntries()
+		const manifest = JSON.stringify(entries, null, 2)
+
+		return `
+const __entries = ${manifest}
+
+function normalizePath(path = '') {
+  return String(path).replace(/^\\/+|\\/+$/g, '')
+}
+
+function pathMatches(entryPath, queryPath) {
+  const e = normalizePath(entryPath)
+  const q = normalizePath(queryPath)
+  if (!q) return true
+  return e === q || e.startsWith(q + '/')
+}
+
+export function getPages(path = '', filter) {
+  const list = __entries.filter((e) => pathMatches(e.path, path))
+  return typeof filter === 'function' ? list.filter(filter) : list
+}
+
+export function getPage(idOrSlug, path = '') {
+  return __entries.find((e) => {
+    if (!pathMatches(e.path, path)) return false
+    return e.id === idOrSlug || e.slug === idOrSlug
+  })
+}
+
+export function getEntries(refs) {
+  return refs.map((r) => getPage(r.id, r.path || ''))
+}
+
+export const getCollection = getPages
+export const getEntry = getPage
+`
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orga-build",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "A simple tool that builds org-mode files into a website",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "cli.js",
     "index.js",
     "index.d.ts",
-    "index.d.ts.map"
+    "index.d.ts.map",
+    "lib/content.d.ts"
   ],
   "exports": {
     ".": {
@@ -19,7 +20,10 @@
       "import": "./index.js"
     },
     "./csr": "./lib/csr.jsx",
-    "./components": "./lib/components.js"
+    "./components": "./lib/components.js",
+    "./client": {
+      "types": "./lib/content.d.ts"
+    }
   },
   "keywords": [
     "orgajs",