methanol 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,58 @@
+# Methanol
+
+Opinionated MDX-first static site generator powered by rEFui + Vite.
+
+For full documentation and examples, see the `methanol-docs` project.
+
+## Quick start
+
+```bash
+# build
+npx methanol build
+
+# dev server
+npx methanol dev
+
+# preview the production build
+npx methanol serve
+```
+
+From this repo, use `node bin/methanol.js [dev|build|serve]`.
+
+## Project layout
+
+Methanol expects a project like this:
+
+```
+pages/        # .mdx pages (file-based routing)
+components/   # JSX/TSX components used by MDX
+public/       # static assets copied/served as-is
+dist/         # build output
+```
+
+## Configuration
+
+Create `methanol.config.{js,mjs,cjs,ts,jsx,tsx,mts,cts}` and export a function:
+
+```js
+export default () => ({
+	// optional: search (Pagefind)
+	pagefind: {
+		enabled: true
+	},
+
+	// optional: code highlighting (Starry Night)
+	starryNight: false,
+
+	// optional: theme sources
+	theme: {
+		sources: {
+			'/.my-theme': './sources'
+		}
+	}
+})
+```
+
+## CLI notes
+
+- `methanol preview` is an alias for `methanol serve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "methanol",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Static site generator powered by rEFui and MDX",
   "main": "./index.js",
   "type": "module",
@@ -16,6 +16,15 @@
   "bin": {
     "methanol": "./bin/methanol.js"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "themes/",
+    "index.js",
+    "LICENSE",
+    "README.md",
+    "banner.txt"
+  ],
   "dependencies": {
     "@mdx-js/mdx": "^3.1.1",
     "@sindresorhus/fnv1a": "^3.1.0",

package/src/config.js

@@ -34,8 +34,10 @@ const CONFIG_FILENAMES = [
 	'methanol.config.mjs',
 	'methanol.config.cjs',
 	'methanol.config.ts',
+	'methanol.config.jsx',
 	'methanol.config.mts',
-	'methanol.config.cts'
+	'methanol.config.cts',
+	'methanol.config.tsx'
 ]
 
 const resolveRootPath = (value) => {
@@ -78,7 +80,7 @@ const resolveThemePublicDir = (root, value) => {
 }
 
 const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj || {}, key)
-const normalizeResources = (value, root) => {
+const normalizeSources = (value, root) => {
 	if (!value) return []
 	const entries = []
 	const addEntry = (find, replacement) => {
@@ -120,7 +122,7 @@ const resolvePagefindEnabled = (config) => {
 const resolvePagefindOptions = (config) => {
 	const value = config?.pagefind
 	if (!value || typeof value !== 'object') return null
-	const { enabled, options, ...rest } = value
+	const { enabled, options, build, buildOptions, ...rest } = value
 	if (options && typeof options === 'object') {
 		return { ...options }
 	}
@@ -130,16 +132,42 @@ const resolvePagefindOptions = (config) => {
 	return null
 }
 
-const resolvePagefindBuildOptions = (config) => {
+const resolvePagefindBuild = (config) => {
 	const value = config?.pagefind
 	if (!value || typeof value !== 'object') return null
-	const buildOptions = value.buildOptions || value.build
-	if (buildOptions && typeof buildOptions === 'object') {
-		return { ...buildOptions }
+	const build = value.build
+	if (build && typeof build === 'object') {
+		return { ...build }
 	}
 	return null
 }
 
+const resolveStarryNightConfig = (value) => {
+	if (value == null) return { enabled: false, options: null }
+	if (typeof value === 'boolean') {
+		return { enabled: value, options: null }
+	}
+	if (typeof value !== 'object') {
+		return { enabled: false, options: null }
+	}
+	const { enabled, options, ...rest } = value
+	if (enabled === false) return { enabled: false, options: null }
+	if (options && typeof options === 'object') {
+		return { enabled: true, options: { ...options } }
+	}
+	if (Object.keys(rest).length) {
+		return { enabled: true, options: { ...rest } }
+	}
+	return { enabled: true, options: null }
+}
+
+const normalizeHooks = (value) => {
+	if (!value) return []
+	if (typeof value === 'function') return [value]
+	if (Array.isArray(value)) return value.filter((entry) => typeof entry === 'function')
+	return []
+}
+
 const loadConfigModule = async (filePath) => {
 	return import(`${pathToFileURL(filePath).href}?t=${Date.now()}`)
 }
@@ -191,12 +219,12 @@ export const applyConfig = async (config, mode) => {
 	if (mode) {
 		state.CURRENT_MODE = mode
 	}
-	const paths = config.paths || config.dirs || {}
+	// config.paths / config.dirs are intentionally ignored (deprecated)
 
-	const pagesDirValue = cli.CLI_PAGES_DIR || config.pagesDir || paths.pages
-	const componentsDirValue = cli.CLI_COMPONENTS_DIR || config.componentsDir || paths.components
-	const distDirValue = cli.CLI_OUTPUT_DIR || config.distDir || paths.dist
-	const publicDirValue = cli.CLI_ASSETS_DIR ?? config.publicDir ?? paths.public
+	const pagesDirValue = cli.CLI_PAGES_DIR || config.pagesDir
+	const componentsDirValue = cli.CLI_COMPONENTS_DIR || config.componentsDir
+	const distDirValue = cli.CLI_OUTPUT_DIR || config.distDir
+	const publicDirValue = cli.CLI_ASSETS_DIR ?? config.publicDir
 
 	const resolvePagesFallback = () => {
 		const pagesPath = resolveFromRoot(root, 'pages', 'pages')
@@ -210,18 +238,18 @@ export const applyConfig = async (config, mode) => {
 		: resolvePagesFallback()
 	state.COMPONENTS_DIR = resolveFromRoot(root, componentsDirValue, 'components')
 	state.STATIC_DIR = resolveOptionalPath(root, publicDirValue, 'public')
-	state.BUILD_DIR = resolveFromRoot(root, config.buildDir || paths.build, 'build')
+	state.BUILD_DIR = resolveFromRoot(root, config.buildDir, 'build')
 	state.DIST_DIR = resolveFromRoot(root, distDirValue, 'dist')
 
-	const userSpecifiedPagesDir = cli.CLI_PAGES_DIR != null || hasOwn(config, 'pagesDir') || hasOwn(paths, 'pages')
+	const userSpecifiedPagesDir = cli.CLI_PAGES_DIR != null || hasOwn(config, 'pagesDir')
 	if (userSpecifiedPagesDir && !existsSync(state.PAGES_DIR)) {
 		throw new Error(`Pages directory not found: ${state.PAGES_DIR}`)
 	}
-	const userSpecifiedComponentsDir = cli.CLI_COMPONENTS_DIR != null || hasOwn(config, 'componentsDir') || hasOwn(paths, 'components')
+	const userSpecifiedComponentsDir = cli.CLI_COMPONENTS_DIR != null || hasOwn(config, 'componentsDir')
 	if (userSpecifiedComponentsDir && !existsSync(state.COMPONENTS_DIR)) {
 		throw new Error(`Components directory not found: ${state.COMPONENTS_DIR}`)
 	}
-	const userSpecifiedPublicDir = cli.CLI_ASSETS_DIR != null || hasOwn(config, 'publicDir') || hasOwn(paths, 'public')
+	const userSpecifiedPublicDir = cli.CLI_ASSETS_DIR != null || hasOwn(config, 'publicDir')
 	if (userSpecifiedPublicDir && state.STATIC_DIR !== false && !existsSync(state.STATIC_DIR)) {
 		state.STATIC_DIR = resolveFromRoot(root, publicDirValue, 'public')
 	}
@@ -270,14 +298,31 @@ export const applyConfig = async (config, mode) => {
 	) {
 		state.STATIC_DIR = state.THEME_PUBLIC_DIR
 	}
-	state.RESOURCES = normalizeResources(state.USER_THEME.resources, themeRoot)
+	state.SOURCES = normalizeSources(state.USER_THEME.sources, themeRoot)
 	state.USER_VITE_CONFIG = config.vite || null
 	state.USER_MDX_CONFIG = config.mdx || null
 	state.RESOLVED_MDX_CONFIG = undefined
 	state.RESOLVED_VITE_CONFIG = undefined
 	state.PAGEFIND_ENABLED = resolvePagefindEnabled(config)
 	state.PAGEFIND_OPTIONS = resolvePagefindOptions(config)
-	state.PAGEFIND_BUILD_OPTIONS = resolvePagefindBuildOptions(config)
+	state.PAGEFIND_BUILD = resolvePagefindBuild(config)
+	state.USER_PRE_BUILD_HOOKS = normalizeHooks(config.preBuild)
+	state.USER_POST_BUILD_HOOKS = normalizeHooks(config.postBuild)
+	state.USER_PRE_BUNDLE_HOOKS = normalizeHooks(config.preBundle)
+	state.USER_POST_BUNDLE_HOOKS = normalizeHooks(config.postBundle)
+	state.THEME_PRE_BUILD_HOOKS = normalizeHooks(state.USER_THEME?.preBuild)
+	state.THEME_POST_BUILD_HOOKS = normalizeHooks(state.USER_THEME?.postBuild)
+	state.THEME_PRE_BUNDLE_HOOKS = normalizeHooks(state.USER_THEME?.preBundle)
+	state.THEME_POST_BUNDLE_HOOKS = normalizeHooks(state.USER_THEME?.postBundle)
+	const starryNight = resolveStarryNightConfig(config.starryNight)
+	const cliCodeHighlighting = cli.CLI_CODE_HIGHLIGHTING
+	if (cliCodeHighlighting != null) {
+		state.STARRY_NIGHT_ENABLED = cliCodeHighlighting === true
+		state.STARRY_NIGHT_OPTIONS = cliCodeHighlighting === true ? starryNight.options : null
+	} else {
+		state.STARRY_NIGHT_ENABLED = starryNight.enabled
+		state.STARRY_NIGHT_OPTIONS = starryNight.enabled ? starryNight.options : null
+	}
 
 	if (cli.CLI_INTERMEDIATE_DIR) {
 		state.INTERMEDIATE_DIR = resolveFromRoot(root, cli.CLI_INTERMEDIATE_DIR, 'build')

package/src/dev-server.js

@@ -19,7 +19,8 @@
  */
 
 import { existsSync } from 'fs'
-import { resolve, dirname, extname, join, basename } from 'path'
+import { readFile } from 'fs/promises'
+import { resolve, dirname, extname, join, basename, relative } from 'path'
 import { fileURLToPath } from 'url'
 import chokidar from 'chokidar'
 import { createServer, mergeConfig } from 'vite'
@@ -151,6 +152,48 @@ export const runViteDev = async () => {
 		return mdxPath
 	}
 
+	const resolveHtmlCandidates = (pathname) => {
+		const candidates = []
+		if (pathname === '/' || pathname === '') {
+			candidates.push('/index.html')
+		} else if (pathname.endsWith('.html')) {
+			candidates.push(pathname)
+		} else {
+			candidates.push(`${pathname}.html`)
+			candidates.push(`${pathname}/index.html`)
+		}
+		return candidates.map((candidate) =>
+			resolve(state.PAGES_DIR, candidate.replace(/^\//, ''))
+		)
+	}
+
+	const shouldServeHtml = (relativePath, requestedPath, hasMdx) => {
+		if (hasMdx) return false
+		const baseName = basename(relativePath, '.html')
+		if (baseName.startsWith('_') || baseName.startsWith('.')) return false
+		const excludedDirs = pagesContext?.excludedDirs
+		if (excludedDirs?.size) {
+			const dir = relativePath.split('/').slice(0, -1).join('/')
+			for (const excludedDir of excludedDirs) {
+				if (!excludedDir) return false
+				if (dir === excludedDir || dir.startsWith(`${excludedDir}/`)) {
+					return false
+				}
+			}
+		}
+		const excludedRoutes = pagesContext?.excludedRoutes
+		if (excludedRoutes?.has(requestedPath)) return false
+		const excludedDirPaths = pagesContext?.excludedDirPaths
+		if (excludedDirPaths?.size) {
+			for (const dirPath of excludedDirPaths) {
+				if (requestedPath === dirPath || requestedPath.startsWith(`${dirPath}/`)) {
+					return false
+				}
+			}
+		}
+		return true
+	}
+
 	const htmlMiddleware = async (req, res, next) => {
 		if (!req.url || req.method !== 'GET') {
 			return next()
@@ -206,9 +249,38 @@ export const runViteDev = async () => {
 			? (pagesContext?.pagesByRouteIndex?.get(requestedPath) ?? pagesContext?.pagesByRoute?.get(requestedPath) ?? null)
 			: (pagesContext?.pagesByRoute?.get(requestedPath) ?? null)
 		let filePath = pageMeta?.filePath || resolvePageFile(requestedPath)
+		const hasMdx = Boolean(pageMeta) || existsSync(filePath)
 		let status = 200
 		let renderRoutePath = requestedPath
 
+		if (!hasMdx) {
+			const candidates = resolveHtmlCandidates(pathname)
+			for (const candidate of candidates) {
+				if (!existsSync(candidate)) continue
+				const relativePath = relative(state.PAGES_DIR, candidate).replace(/\\/g, '/')
+				if (relativePath.startsWith('..')) {
+					continue
+				}
+				if (!shouldServeHtml(relativePath, requestedPath, hasMdx)) {
+					continue
+				}
+				try {
+					const html = await readFile(candidate, 'utf-8')
+					const candidateUrl = `/${relativePath}`
+					const transformed = await server.transformIndexHtml(candidateUrl, html)
+					res.statusCode = 200
+					res.setHeader('Content-Type', 'text/html')
+					res.end(transformed)
+					return
+				} catch (err) {
+					console.error(err)
+					res.statusCode = 500
+					res.end('Internal Server Error')
+					return
+				}
+			}
+		}
+
 		if (isExcludedPath()) {
 			if (notFoundPage) {
 				filePath = notFoundPage.filePath
@@ -414,12 +486,13 @@ export const runViteDev = async () => {
 		prevEntry.toc = null
 		pagesContext.refreshPagesTree?.()
 		pagesContext.refreshLanguages?.()
-		if (prevEntry.frontmatter?.title == null) {
-			if (prevEntry.content && prevEntry.content.trim().length) {
-				await compilePageMdx(prevEntry, pagesContext)
-				// Avoid caching a potentially stale render; recompile on request.
-				prevEntry.mdxComponent = null
-			}
+		if (prevEntry.content && prevEntry.content.trim().length) {
+			await compilePageMdx(prevEntry, pagesContext, {
+				lazyPagesTree: true,
+				refreshPagesTree: false
+			})
+			// Avoid caching a potentially stale render; recompile on request.
+			prevEntry.mdxComponent = null
 		}
 		return true
 	}

package/src/main.js

@@ -24,6 +24,7 @@ import { buildHtmlEntries, runViteBuild } from './build-system.js'
 import { runPagefind } from './pagefind.js'
 import { runVitePreview } from './preview-server.js'
 import { cli, state } from './state.js'
+import { HTMLRenderer } from './renderer.js'
 import { readFile } from 'fs/promises'
 
 const printBanner = async () => {
@@ -61,7 +62,39 @@ const main = async () => {
 	const mode = isDev ? 'development' : 'production'
 	const config = await loadUserConfig(mode, cli.CLI_CONFIG_PATH)
 	await applyConfig(config, mode)
+	const hookContext = {
+		mode,
+		root: state.ROOT_DIR,
+		command: normalizedCommand,
+		isDev,
+		isBuild,
+		isPreview,
+		HTMLRenderer,
+		site: {
+			name: state.SITE_NAME,
+			root: state.ROOT_DIR,
+			pagesDir: state.PAGES_DIR,
+			componentsDir: state.COMPONENTS_DIR,
+			publicDir: state.STATIC_DIR,
+			distDir: state.DIST_DIR,
+			mode: state.CURRENT_MODE,
+			pagefind: {
+				enabled: state.PAGEFIND_ENABLED,
+				options: state.PAGEFIND_OPTIONS || null,
+				build: state.PAGEFIND_BUILD || null
+			}
+		},
+		data: {}
+	}
+	const runHooks = async (hooks = [], extra = null) => {
+		const context = extra ? { ...hookContext, ...extra } : hookContext
+		for (const hook of hooks) {
+			await hook(context)
+		}
+	}
 	if (isDev) {
+		await runHooks(state.USER_PRE_BUILD_HOOKS)
+		await runHooks(state.THEME_PRE_BUILD_HOOKS)
 		await runViteDev()
 		return
 	}
@@ -70,11 +103,28 @@ const main = async () => {
 		return
 	}
 	if (isBuild) {
-		const { entry, htmlCache } = await buildHtmlEntries()
+		await runHooks(state.USER_PRE_BUILD_HOOKS)
+		await runHooks(state.THEME_PRE_BUILD_HOOKS)
+		const { entry, htmlCache, pagesContext } = await buildHtmlEntries()
+		const buildContext = pagesContext
+			? {
+					pagesContext,
+					pages: pagesContext.pages,
+					pagesTree: pagesContext.pagesTree,
+					pagesByRoute: pagesContext.pagesByRoute,
+					site: pagesContext.site
+				}
+			: null
+		await runHooks(state.USER_PRE_BUNDLE_HOOKS, buildContext)
+		await runHooks(state.THEME_PRE_BUNDLE_HOOKS, buildContext)
 		await runViteBuild(entry, htmlCache)
+		await runHooks(state.THEME_POST_BUNDLE_HOOKS, buildContext)
+		await runHooks(state.USER_POST_BUNDLE_HOOKS, buildContext)
 		if (state.PAGEFIND_ENABLED) {
 			await runPagefind()
 		}
+		await runHooks(state.THEME_POST_BUILD_HOOKS, buildContext)
+		await runHooks(state.USER_POST_BUILD_HOOKS, buildContext)
 		return
 	}
 	cli.showHelp()