methanol 0.0.18 → 0.0.19

package/README.md

@@ -64,6 +64,10 @@ export default () => ({
 })
 ```
 
+## Themes
+
+Methanol includes built-in themes (`default`, `blog`). Use `--theme <name>` or set `theme: '<name>'` in config. For local themes inside your project, import the theme entry in `methanol.config.*` and pass the theme object/factory.
+
 ## CLI notes
 
 - `methanol preview` is an alias for `methanol serve`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "methanol",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "Static site generator powered by rEFui and MDX",
   "main": "./index.js",
   "type": "module",
@@ -36,7 +36,7 @@
     "hast-util-is-element": "^3.0.0",
     "json5": "^2.2.3",
     "null-prototype-object": "^1.2.5",
-    "refui": "^0.16.4",
+    "refui": "^0.17.1",
     "refurbish": "^0.1.8",
     "rehype-slug": "^6.0.0",
     "rehype-starry-night": "^2.2.0",

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/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/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)

package/themes/default/src/page.jsx

@@ -108,6 +108,8 @@ const PAGE_TEMPLATE = ({ PageContent, ExtraHead, components, ctx }) => {
 				<head>
 					<meta charset="UTF-8" />
 					<meta name="viewport" content="width=device-width" />
+					<meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)" />
+					<meta name="theme-color" content="#09090b" media="(prefers-color-scheme: dark)" />
 					<title>
 						{title} | {siteName}
 					</title>