methanol 0.0.18 → 0.0.20

package/src/workers/build-worker.js

@@ -28,6 +28,7 @@ let initPromise = null
 let pages = []
 let pagesContext = null
 let components = null
+let mdxPageIds = new Set()
 
 const ensureInit = async () => {
 	if (initPromise) return initPromise
@@ -112,31 +113,27 @@ const logPageError = (phase, page, error) => {
 const handleSetPages = async (message) => {
 	const { pages: nextPages, excludedRoutes = [], excludedDirs = [] } = message || {}
 	pages = Array.isArray(nextPages) ? nextPages : []
+	mdxPageIds = new Set()
 	await rebuildPagesContext(new Set(excludedRoutes), new Set(excludedDirs))
 }
 
 const handleSyncUpdates = async (message) => {
-	const { updates = [], titles = null, excludedRoutes = null, excludedDirs = null } = message || {}
-	if (Array.isArray(titles)) {
-		for (let i = 0; i < titles.length; i += 1) {
-			const page = pages[i]
-			if (!page) continue
-			if (titles[i] !== undefined) {
-				page.title = titles[i]
-			}
-		}
-	}
+	const { updates = [], excludedRoutes = null, excludedDirs = null } = message || {}
 	for (const update of updates) {
 		const page = pages[update.id]
 		if (!page) continue
 		if (update.title !== undefined) page.title = update.title
-		if (update.toc !== undefined) page.toc = update.toc
 	}
-	await rebuildPagesContext(
-		excludedRoutes ? new Set(excludedRoutes) : pagesContext?.excludedRoutes || new Set(),
-		excludedDirs ? new Set(excludedDirs) : pagesContext?.excludedDirs || new Set()
-	)
-	for (const page of pages) {
+	if (!pagesContext || excludedRoutes || excludedDirs) {
+		await rebuildPagesContext(
+			excludedRoutes ? new Set(excludedRoutes) : pagesContext?.excludedRoutes || new Set(),
+			excludedDirs ? new Set(excludedDirs) : pagesContext?.excludedDirs || new Set()
+		)
+	} else {
+		pagesContext.refreshPagesTree?.(true)
+	}
+	for (const id of mdxPageIds) {
+		const page = pages[id]
 		if (!page?.mdxCtx) continue
 		refreshMdxCtx(page)
 	}
@@ -159,6 +156,7 @@ const handleCompile = async (message) => {
 				lazyPagesTree: true,
 				refreshPagesTree: false
 			})
+			mdxPageIds.add(id)
 			updates.push({ id, title: page.title, toc: page.toc || null })
 		} catch (error) {
 			logPageError('MDX compile', page, error)
@@ -173,7 +171,6 @@ const handleCompile = async (message) => {
 const handleRender = async (message) => {
 	const { ids = [], stage } = message || {}
 	const { renderHtml } = await import('../mdx.js')
-	const results = []
 	let completed = 0
 	for (const id of ids) {
 		const page = pages[id]
@@ -190,7 +187,7 @@ const handleRender = async (message) => {
 				pagesContext,
 				pageMeta: page
 			})
-			results.push({ id, html })
+			parentPort?.postMessage({ type: 'result', stage, result: { id, html } })
 		} catch (error) {
 			logPageError('MDX render', page, error)
 			throw error
@@ -198,7 +195,35 @@ const handleRender = async (message) => {
 		completed += 1
 		parentPort?.postMessage({ type: 'progress', stage, completed })
 	}
-	return results
+}
+
+const handleRss = async (message) => {
+	const { ids = [], stage } = message || {}
+	const { renderPageContent } = await import('../mdx.js')
+	let completed = 0
+	for (const id of ids) {
+		const page = pages[id]
+		if (!page) {
+			completed += 1
+			parentPort?.postMessage({ type: 'progress', stage, completed })
+			continue
+		}
+		try {
+			const content = await renderPageContent({
+				routePath: page.routePath,
+				path: page.path,
+				components,
+				pagesContext,
+				pageMeta: page
+			})
+			parentPort?.postMessage({ type: 'result', stage, result: { id, content } })
+		} catch (error) {
+			logPageError('RSS render', page, error)
+			throw error
+		}
+		completed += 1
+		parentPort?.postMessage({ type: 'progress', stage, completed })
+	}
 }
 
 parentPort?.on('message', async (message) => {
@@ -221,8 +246,13 @@ parentPort?.on('message', async (message) => {
 			return
 		}
 		if (type === 'render') {
-			const results = await handleRender(message)
-			parentPort?.postMessage({ type: 'done', stage, results })
+			await handleRender(message)
+			parentPort?.postMessage({ type: 'done', stage })
+			return
+		}
+		if (type === 'rss') {
+			await handleRss(message)
+			parentPort?.postMessage({ type: 'done', stage })
 			return
 		}
 	} catch (error) {

package/themes/README.md

@@ -0,0 +1,52 @@
+# Themes
+
+Methanol ships with built-in themes under `themes/`.
+
+## Built-in themes
+
+- `default`: Documentation-style theme (sidebar + ToC).
+- `blog`: Blog theme (post list, tags/categories UI).
+
+## Using a theme
+
+CLI:
+
+```bash
+methanol build --theme blog
+methanol dev --theme default
+```
+
+Config (`methanol.config.*`):
+
+```js
+export default () => ({
+	theme: 'blog'
+})
+```
+
+## Using a local theme (in your project)
+
+Theme name resolution only applies when `theme` is a string (built-in or `methanol-theme-xxx` from `node_modules`).
+If your theme lives inside your project, import it and pass the theme object/factory:
+
+```js
+import createTheme from './themes/my-theme/index.js'
+
+export default () => ({
+	theme: createTheme()
+})
+```
+
+## Publishing a theme
+
+If you publish a theme as an npm package named `methanol-theme-xxx`, users can enable it via `--theme xxx` or `theme: 'xxx'`.
+
+## Theme structure (convention)
+
+- `index.js`: entrypoint that exports a theme object or a factory function (recommended).
+- `src/`: theme runtime/template modules (e.g. `src/page.jsx`).
+- `components/`: theme components (used by MDX).
+- `pages/`: theme-provided pages (e.g. `_404.mdx`, `offline.mdx`).
+- `public/`: theme static assets (merged with user `public/`).
+- `sources/`: extra source mappings exposed via `theme.sources`.
+

package/themes/blog/README.md

@@ -1,26 +1,46 @@
 # Blog Theme
 
-A simple, clean blog theme for Methanol.
+A blog theme for Methanol.
 
 ## Features
-- Clean typography
-- Post list on homepage
-- Responsive design
-- Dark mode support (via system preference)
+
+- Post list and post pages
+- Category/collection views (theme-provided client UI)
+- Responsive layout
 
 ## Usage
 
-To use this theme, configure your Methanol project to point to this directory.
+CLI:
+
+```bash
+methanol build --theme blog
+methanol dev --theme blog
+```
+
+Config (`methanol.config.*`):
 
 ```js
-// methanol.config.js
-export default {
-  theme: './themes/blog',
-  // ...
-}
+export default () => ({
+	theme: 'blog'
+})
 ```
 
 ## Structure
-- `src/page.jsx`: Main layout template.
-- `sources/style.css`: Stylesheet.
-- `pages/`: Default pages (Home, 404, Offline).
+
+- `src/page.jsx`: main layout template
+- `pages/`: theme pages (including special pages like `_404.mdx` and `offline.mdx` when present)
+- `components/`: theme components used by MDX
+- `public/`: theme static assets
+- `sources/`: theme source mappings (used by `theme.sources`)
+
+## Local development
+
+If you want to use the theme from a local folder (instead of built-in name / npm package), import it in config:
+
+```js
+import createBlogTheme from './themes/blog/index.js'
+
+export default () => ({
+	theme: createBlogTheme()
+})
+```

package/themes/blog/sources/style.css

@@ -98,9 +98,31 @@ a {
     flex-shrink: 0;
 }
 
+.header-actions .rss-link {
+	color: var(--text-muted);
+	text-decoration: none;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: 2.25rem;
+	height: 2.25rem;
+	border-radius: 999px;
+	transition: all 0.2s;
+}
+
+.header-actions .rss-link:hover {
+	color: var(--text);
+	background: var(--bg-soft);
+}
+
+.rss-label {
+	display: none;
+}
+
 .blog-nav {
 	display: flex;
 	gap: 1.25rem;
+    align-items: center;
 }
 
 .blog-nav a {
@@ -551,11 +573,29 @@ h6:hover .heading-anchor, h6:active .heading-anchor {
 		visibility: visible;
 	}
     
-    .nav-toggle:checked ~ .nav-toggle-label {
-        color: var(--primary);
+    	.nav-toggle:checked ~ .nav-toggle-label {
+            color: var(--primary);
+        }
+    
+        .header-actions .rss-link {
+            width: 100%;
+            height: auto;
+            border-radius: 0;
+            justify-content: flex-start;
+            padding: 0.75rem var(--container-px);
+            background: transparent !important;
+            font-weight: 500;
+        }
+    
+        .header-actions .rss-link:hover {
+            color: var(--primary);
+        }
+    
+        .rss-label {
+            display: inline;
+            margin-left: 0.5rem;
+        }
     }
-}
-
 @media (max-width: 640px) {
     .blog-header { padding: 1rem 0; }
     .header-container { gap: 1rem; }

package/themes/blog/src/layout-categories.jsx

@@ -40,9 +40,9 @@ const renderPostCards = (posts = []) =>
 		)
 	})
 
-export const LayoutCategories = ({ PageContent, title, pages, navLinks, components }) => {
+export const LayoutCategories = ({ PageContent, title, pages, navLinks, components, currentRoutePath, hiddenPrefixes }) => {
 	const { CategoryView } = components || {}
-	const filteredPosts = filterBlogPosts(pages, navLinks)
+	const filteredPosts = filterBlogPosts(pages, navLinks, { currentRoutePath, hiddenPrefixes })
 	const staticPosts = mapStaticPosts(filteredPosts)
 	const categories = collectCategories(filteredPosts)
 	const visiblePosts = staticPosts.slice(0, 10)

package/themes/blog/src/layout-collections.jsx

@@ -39,9 +39,9 @@ const renderPostCards = (posts = [], collectionTitles = {}) =>
 		)
 	})
 
-export const LayoutCollections = ({ PageContent, title, pages, pagesByRoute, navLinks, components }) => {
+export const LayoutCollections = ({ PageContent, title, pages, pagesByRoute, navLinks, components, currentRoutePath, hiddenPrefixes }) => {
 	const { CollectionView } = components || {}
-	const filteredPosts = filterBlogPosts(pages, navLinks)
+	const filteredPosts = filterBlogPosts(pages, navLinks, { currentRoutePath, hiddenPrefixes })
 	const staticPosts = mapStaticPosts(filteredPosts)
 	const collectionTitles = collectCollectionTitles(staticPosts, pagesByRoute)
 	const visiblePosts = staticPosts.slice(0, 10)

package/themes/blog/src/layout-home.jsx

@@ -35,9 +35,9 @@ const renderPostCards = (posts = []) =>
 		)
 	})
 
-export const LayoutHome = ({ PageContent, pages, navLinks, components }) => {
+export const LayoutHome = ({ PageContent, pages, navLinks, components, currentRoutePath, hiddenPrefixes }) => {
 	const { PostList } = components || {}
-	const filteredPosts = filterBlogPosts(pages, navLinks)
+	const filteredPosts = filterBlogPosts(pages, navLinks, { currentRoutePath, hiddenPrefixes })
 	const staticPosts = mapStaticPosts(filteredPosts)
 	const visiblePosts = staticPosts.slice(0, 10)
 	const hasMore = staticPosts.length > visiblePosts.length

package/themes/blog/src/page.jsx

@@ -24,7 +24,7 @@ import { LayoutCategories } from './layout-categories.jsx'
 import { LayoutCollections } from './layout-collections.jsx'
 import { LayoutPost } from './layout-post.jsx'
 
-const Header = ({ siteName, navLinks, components, pagefindOptions }) => {
+const Header = ({ siteName, navLinks, components, pagefindOptions, rssHref, feedLabel }) => {
 	const { ThemeSearchBox } = components || {}
 	return (
 		<header class="blog-header">
@@ -34,7 +34,6 @@ const Header = ({ siteName, navLinks, components, pagefindOptions }) => {
 				</a>
 				<div class="header-actions">
 					{ThemeSearchBox && <ThemeSearchBox options={pagefindOptions} />}
-					
 					<input type="checkbox" id="nav-toggle" class="nav-toggle" />
 					<label for="nav-toggle" class="nav-toggle-label">
 						<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
@@ -50,6 +49,25 @@ const Header = ({ siteName, navLinks, components, pagefindOptions }) => {
 								{link.label}
 							</a>
 						))}
+						{rssHref ? (
+							<a class="rss-link" href={rssHref} aria-label={feedLabel} title={feedLabel}>
+								<svg
+									width="20"
+									height="20"
+									viewBox="0 0 24 24"
+									fill="none"
+									stroke="currentColor"
+									stroke-width="2"
+									stroke-linecap="round"
+									stroke-linejoin="round"
+								>
+									<path d="M4 11a9 9 0 0 1 9 9"></path>
+									<path d="M4 4a16 16 0 0 1 16 16"></path>
+									<circle cx="5" cy="19" r="1"></circle>
+								</svg>
+								<span class="rss-label">{feedLabel}</span>
+							</a>
+						) : null}
 					</nav>
 				</div>
 			</div>
@@ -57,11 +75,11 @@ const Header = ({ siteName, navLinks, components, pagefindOptions }) => {
 	)
 }
 
-const Footer = ({ siteName }) => (
+const Footer = ({ siteName, owner }) => (
 	<footer class="blog-footer">
 		<div class="container">
 			<p>
-				&copy; {new Date().getFullYear()} {siteName}. Powered by <a href="https://methanol.sudoMaker.com">Methanol</a>.
+				&copy; {new Date().getFullYear()} {owner || siteName}. Powered by <a href="https://methanol.sudoMaker.com">Methanol</a>.
 			</p>
 		</div>
 	</footer>
@@ -70,6 +88,7 @@ const Footer = ({ siteName }) => (
 const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) => {
 	const page = ctx.page
 	const siteName = ctx.site.name || 'Methanol Blog'
+	const siteOwner = ctx.site.owner || null
 	const title = page.title || siteName
 
 	const isHome = page.routePath === '/'
@@ -90,11 +109,27 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) =>
 		return link
 	})
 
+	const currentRoutePath = page.routePath || '/'
 	const isCategoriesPage = page.routePath === '/categories'
 	const isCollectionsPage = page.routePath === '/collections'
+	const hiddenPrefixes = (ctx.pages || [])
+		.filter(
+			(entry) =>
+				entry.isIndex &&
+				entry.hidden &&
+				entry.routePath &&
+				entry.routePath !== '/' &&
+				entry.routePath !== '/404' &&
+				entry.routePath !== '/offline'
+		)
+		.map((entry) => (entry.routePath.endsWith('/') ? entry.routePath : `${entry.routePath}/`))
 
 	const pagefindEnabled = ctx.site.pagefind?.enabled !== false
 	const pagefindOptions = ctx.site.pagefind?.options || null
+	const feedInfo = ctx.site.feed
+	const rssHref = feedInfo?.enabled ? feedInfo.href : null
+	const feedType = feedInfo?.atom ? 'application/atom+xml' : 'application/rss+xml'
+	const feedLabel = feedInfo?.atom ? 'Atom' : 'RSS'
 
 	return (
 		<>
@@ -107,6 +142,7 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) =>
 						{title} | {siteName}
 					</title>
 					<link rel="stylesheet" href="/.methanol_theme_blog/style.css" />
+					{rssHref ? <link rel="alternate" type={feedType} title={`${siteName} ${feedLabel}`} href={rssHref} /> : null}
 					<ExtraHead />
 				</head>
 				<body>
@@ -116,10 +152,19 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) =>
 							navLinks={resolvedNavLinks}
 							components={pagefindEnabled ? components : {}}
 							pagefindOptions={pagefindOptions}
+							rssHref={rssHref}
+							feedLabel={feedLabel}
 						/>
 						<main class="container main-content">
 							{isHome ? (
-								<LayoutHome PageContent={PageContent} pages={ctx.pages} navLinks={navLinks} components={components} />
+								<LayoutHome
+									PageContent={PageContent}
+									pages={ctx.pages}
+									navLinks={navLinks}
+									components={components}
+									currentRoutePath={currentRoutePath}
+									hiddenPrefixes={hiddenPrefixes}
+								/>
 							) : isCategoriesPage ? (
 								<LayoutCategories
 									PageContent={PageContent}
@@ -127,6 +172,8 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) =>
 									pages={ctx.pages}
 									navLinks={navLinks}
 									components={components}
+									currentRoutePath={currentRoutePath}
+									hiddenPrefixes={hiddenPrefixes}
 								/>
 							) : isCollectionsPage ? (
 								<LayoutCollections
@@ -136,12 +183,14 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx, withBase }) =>
 									pagesByRoute={ctx.pagesByRoute}
 									navLinks={navLinks}
 									components={components}
+									currentRoutePath={currentRoutePath}
+									hiddenPrefixes={hiddenPrefixes}
 								/>
 							) : (
 								<LayoutPost PageContent={PageContent} title={title} page={page} />
 							)}
 						</main>
-						<Footer siteName={siteName} />
+						<Footer siteName={siteName} owner={siteOwner} />
 					</div>
 				</body>
 			</html>

package/themes/blog/src/post-utils.js

@@ -29,15 +29,25 @@ const isBlogPost = (page) => {
 	return true
 }
 
-export const filterBlogPosts = (pages, navLinks = []) => {
+export const filterBlogPosts = (pages, navLinks = [], options = {}) => {
 	const excluded = new Set((navLinks || []).map((link) => link?.href).filter(Boolean))
 	const list = (pages || []).filter((page) => isBlogPost(page) && !excluded.has(page.routeHref))
-	list.sort((a, b) => {
+	const { currentRoutePath, hiddenPrefixes } = options || {}
+	const activeRoute = typeof currentRoutePath === 'string' ? currentRoutePath : ''
+	const hiddenScopes = Array.isArray(hiddenPrefixes) ? hiddenPrefixes.filter(Boolean) : []
+	const filtered = hiddenScopes.length
+		? list.filter((page) => {
+				const hiddenScope = hiddenScopes.find((prefix) => page.routePath?.startsWith(prefix))
+				if (!hiddenScope) return true
+				return activeRoute.startsWith(hiddenScope)
+			})
+		: list
+	filtered.sort((a, b) => {
 		const dateA = new Date(a.frontmatter?.date || a.stats?.createdAt || 0)
 		const dateB = new Date(b.frontmatter?.date || b.stats?.createdAt || 0)
 		return dateB - dateA
 	})
-	return list
+	return filtered
 }
 
 export const getExcerpt = (page) => extractExcerpt(page)

package/themes/default/README.md

@@ -0,0 +1,26 @@
+# Default Theme
+
+The default Methanol theme is designed for documentation sites (sidebar navigation + table of contents).
+
+## Enable
+
+CLI:
+
+```bash
+methanol build --theme default
+methanol dev --theme default
+```
+
+Config:
+
+```js
+export default () => ({
+	theme: 'default'
+})
+```
+
+## Notes
+
+- User `public/` assets override theme-provided `public/` assets.
+- Theme pages under `pages/` can provide special routes like `_404.mdx` and `offline.mdx`.
+

package/themes/default/components/ThemeColorSwitch.client.jsx

@@ -75,6 +75,19 @@ export default function () {
 		localStorage.setItem('methanol-theme', theme.value)
 		document.documentElement.classList.toggle('light', theme.value === 'light')
 		document.documentElement.classList.toggle('dark', theme.value === 'dark')
+
+		const metas = document.querySelectorAll('meta[name="theme-color"]')
+		let meta = metas[0]
+		if (!meta) {
+			meta = document.createElement('meta')
+			meta.name = 'theme-color'
+			document.head.appendChild(meta)
+		}
+		for (let i = 1; i < metas.length; i++) {
+			metas[i].remove()
+		}
+		meta.content = theme.value === 'light' ? '#ffffff' : '#09090b'
+		meta.removeAttribute('media')
 	}
 
 	const CurrentIcon = $(() => {

package/themes/default/sources/style.css

@@ -470,6 +470,33 @@ a {
 		flex-shrink: 0; /* Prevent footer from shrinking */
 	}
 
+	.sidebar-footer .rss-link {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		width: 2.25rem;
+		height: 2.25rem;
+		background: var(--surface-muted);
+		border: 1px solid var(--border);
+		border-radius: var(--radius);
+		color: var(--text);
+		transition: all 0.2s ease;
+		flex-shrink: 0;
+	}
+
+	.sidebar-footer .rss-link:hover {
+		background: var(--hover-bg);
+		border-color: var(--muted);
+	}
+
+	.sidebar-footer .rss-link:active {
+		transform: scale(0.96);
+	}
+
+	.sidebar-footer .rss-link svg {
+		opacity: 0.8;
+	}
+
 	.lang-switch-wrapper {
 		flex: 1;
 		position: relative;
@@ -1825,4 +1852,3 @@ a {
 		size: auto;
 	}
 }
-

package/themes/default/sources/theme-prepare.js

@@ -25,6 +25,19 @@
 	document.documentElement.classList.toggle('light', theme === 'light')
 	document.documentElement.classList.toggle('dark', theme === 'dark')
 
+	const metas = document.querySelectorAll('meta[name="theme-color"]')
+	let meta = metas[0]
+	if (!meta) {
+		meta = document.createElement('meta')
+		meta.name = 'theme-color'
+		document.head.appendChild(meta)
+	}
+	for (let i = 1; i < metas.length; i++) {
+		metas[i].remove()
+	}
+	meta.content = theme === 'light' ? '#ffffff' : '#09090b'
+	meta.removeAttribute('media')
+
 	const savedAccent = localStorage.getItem('methanol-accent')
 	if (savedAccent && savedAccent !== 'default') {
 		document.documentElement.classList.add('accent-' + savedAccent)