retypeset-odyssey 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 radishzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# Retypeset Odyssey
+
+A fork of [astro-theme-retypeset](https://github.com/radishzzz/astro-theme-retypeset) — extended to work both as a standalone Astro template **and** as an installable npm package for content-only repositories.
+
+Powering [zhenjia.org](https://zhenjia.org).
+
+## What's different from upstream
+
+This fork adds the ability to consume the theme as a dependency, so you can keep your content in a separate repository and pull the theme via `pnpm install`. The original "clone and edit" workflow still works unchanged.
+
+| Use case | Approach |
+|----------|----------|
+| Personal blog, all in one repo | Fork & clone (same as upstream Retypeset) |
+| Content repo + reusable theme | Install `retypeset-odyssey` as a dependency |
+
+Other deltas from upstream: trilingual content support (zh / en / ja) with `.en.md` / `.ja.md` filename convention, tag URL encoding (so tags like `CI/CD` work), legacy Hexo `abbrlink` redirects, GitHub Actions translation pipeline.
+
+## Features
+
+- Built with Astro 5 and UnoCSS
+- SEO, Sitemap, OpenGraph (with generated cards), RSS, MDX, LaTeX, Mermaid, TOC
+- i18n with route-level language switching
+- Light / Dark mode with view transitions
+- Pagefind full-text search
+- Responsive, typography-first layout
+
+## Usage A — Standalone (fork & clone)
+
+```bash
+git clone https://github.com/lifeodyssey/retypeset-odyssey.git
+cd retypeset-odyssey
+pnpm install
+pnpm dev
+```
+
+Edit `src/config.ts` for site settings. Put markdown in `content/{posts,notes,journals}/`. Build with `pnpm build`.
+
+## Usage B — As an npm package
+
+Set up your own minimal Astro project that consumes this theme. One install, one YAML, one line of Astro config.
+
+```jsonc
+// package.json
+{
+  "name": "my-blog",
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build"
+  },
+  "dependencies": {
+    "astro": "^5.17.1",
+    "retypeset-odyssey": "github:lifeodyssey/retypeset-odyssey"
+  }
+}
+```
+
+```ts
+// astro.config.ts
+import { defineConfig } from 'astro/config'
+import retypeset from 'retypeset-odyssey/integration'
+
+export default defineConfig({
+  integrations: [retypeset()],
+})
+```
+
+```yaml
+# retypeset.config.yaml — at project root. Any subset of keys; the rest fall back to defaults.
+site:
+  title: My Blog
+  subtitle: Hello world
+  author: Your Name
+  url: https://your-domain.com
+global:
+  locale: en
+  moreLocales: []
+footer:
+  links:
+    - name: RSS
+      url: /atom.xml
+  startYear: 2024
+```
+
+```ts
+// src/content.config.ts
+export { collections } from 'retypeset-odyssey/content-config'
+```
+
+Then put markdown directly in your repo:
+
+```
+content/
+├── posts/
+│   ├── article.md          (zh, default)
+│   ├── article.en.md       (English)
+│   └── article.ja.md       (Japanese)
+├── notes/
+└── journals/
+```
+
+Build:
+
+```bash
+pnpm install
+pnpm build  # → dist/
+```
+
+### What the integration does
+
+- Loads `default-config.yaml` (shipped with the package), deep-merges your `retypeset.config.yaml` on top, and validates the result with Zod. The merged config is exposed to the theme via a Vite virtual module (`virtual:retypeset/config`) — every theme file that does `import ... from '@/config'` automatically picks up your overrides without any code change on your side.
+- Drives Astro's top-level config from the same YAML: `site`, `base`, `build.format`, `trailingSlash`, `prefetch`, `i18n`, and `image.domains` are all set automatically.
+- Registers UnoCSS (with the theme's `uno.config.ts`), MDX, partytown, sitemap, pagefind, and astro-compress — so you do not import any of them yourself.
+- Injects all theme routes (`posts/[slug]`, `tags/[tag]`, RSS, OG images, etc.) via Astro's `injectRoute` API.
+- Points `publicDir` at the package's own `public/`, so fonts, icons, and other assets ship without copying.
+
+### Configuration reference
+
+The full schema lives in [`src/config-schema.ts`](./src/config-schema.ts) and the defaults in [`default-config.yaml`](./default-config.yaml). Top-level groups: `site`, `color`, `global`, `comment`, `seo`, `footer`, `preload`. Any field you do not set in your YAML falls back to the default. Validation errors surface at `astro build` time with a clear path into the YAML.
+
+## Customization
+
+- **Site config**: edit `default-config.yaml` (standalone) or write your own `retypeset.config.yaml` next to `astro.config.ts` (package consumers). Any subset of keys is allowed; the rest fall back to the defaults.
+- **About pages**: place markdown in `src/content/about/about-{zh|en|ja}.md`.
+- **Static assets** (favicon, OG logo, fonts): standalone users edit `public/`; package consumers inherit from the installed theme.
+
+## Migrating from Hexo
+
+If you're coming from Hexo (or another markdown-first SSG) and want to bring your existing posts over, this theme ships with a one-off migration helper plus a 301-bridge generator for SEO.
+
+### Quick path
+
+1. **Start from the starter template** — [retypeset-starter](https://github.com/lifeodyssey/retypeset-starter) is a minimal consumer repo (one `package.json`, one `astro.config.ts`, one YAML). Click *Use this template* on GitHub, clone the new repo, then `pnpm install`.
+
+2. **Bring your Hexo posts over with the migration script.** Copy `scripts/migration/migrate-hexo.ts` out of the installed theme into your own repo, edit the two source/target path constants at the top, then:
+
+   ```bash
+   pnpm tsx scripts/migrate-hexo.ts
+   ```
+
+   It walks every file under your Hexo `source/_posts/`, converts the frontmatter (`date` → `published`, accepts string-or-array `tags`/`categories`, preserves `abbrlink`, drops Hexo-private fields gracefully), and writes the result to `content/posts/`. Multilingual variants use the `.en.md` / `.ja.md` suffix convention.
+
+3. **(Optional) verify abbrlinks weren't lost.** A sibling `validate-abbrlinks.ts` cross-checks every output file's `abbrlink` against the original Hexo source so you can catch silent drops.
+
+4. **Run `pnpm dev`** and click around. If a post fails frontmatter validation, the integration's Zod schema is permissive — most Hexo frontmatter quirks are accepted — but missing `title` or unparseable `date` will surface as a clear error pointing at the file.
+
+### Preserve your SEO
+
+If your Hexo site was deployed under a domain you can't drop (e.g. `username.github.io`), use [`scripts/generate-redirect-pages.mjs`](https://github.com/lifeodyssey/Blog-src/blob/main/scripts/generate-redirect-pages.mjs) (in the content-repo example, not in this package) to generate a per-page 301 bridge: for every old `posts/<abbrlink>.html` URL, it emits a static HTML with `<meta http-equiv="refresh">` + `<link rel="canonical">` pointing at the new domain. Deploy the generated files to the old host and search engine weight transfers over.
+
+### Story version
+
+For a long-form walkthrough of why the migration was structured this way, including the trade-offs around frontmatter compatibility, SEO continuity, and `abbrlink` preservation, see [我是怎么用 AI 把博客从 Hexo 迁到 Astro 的](https://zhenjia.org/posts/how-i-migrated-blog-with-ai-v3) (Chinese; the migration was originally documented from a non-frontend developer's perspective).
+
+## Credits
+
+Forked from [astro-theme-retypeset](https://github.com/radishzzz/astro-theme-retypeset) by [@radishzzz](https://github.com/radishzzz). Upstream inspirations:
+
+- [Typography](https://github.com/moeyua/astro-theme-typography)
+- [Fuwari](https://github.com/saicaca/fuwari)
+- [Redefine](https://github.com/EvanNotFound/hexo-theme-redefine)
+- [AstroPaper](https://github.com/satnaing/astro-paper)
+- [heti](https://github.com/sivan/heti)
+- [EarlySummerSerif](https://github.com/GuiWonder/EarlySummerSerif)
+
+## License
+
+Same as upstream: MIT (see `LICENSE`).

package/astro.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'astro/config'
+import retypeset from './integration'
+
+/**
+ * Standalone-mode Astro config.
+ *
+ * When this repo is checked out and used directly (Usage A in README), the
+ * integration does all the heavy lifting — it loads `default-config.yaml`
+ * (and any `retypeset.config.yaml` placed alongside this file), wires up
+ * UnoCSS / MDX / partytown / sitemap / pagefind / compress, sets the
+ * top-level Astro config from the YAML, and injects every route.
+ *
+ * Package consumers (Usage B) should mirror this file — `integrations:
+ * [retypeset()]` is all they need.
+ */
+export default defineConfig({
+  integrations: [retypeset()],
+})

package/default-config.yaml

@@ -0,0 +1,136 @@
+# Retypeset Odyssey — default theme configuration.
+#
+# This file is the authoritative source of defaults. A consumer can override
+# any subset of these keys in their own `retypeset.config.yaml` at the project
+# root; values are deep-merged on top of this file.
+
+# ---- SITE -------------------------------------------------------------------
+site:
+  # Site title.
+  title: Life Odyssey
+  # Site subtitle (tagline).
+  subtitle: 人生若只如初见
+  # Site description (for SEO + RSS).
+  description: A personal blog about life, technology, and reflections.
+  # Use i18n title/subtitle/description from src/i18n/ui.ts instead of the
+  # static strings above.
+  i18nTitle: true
+  # Author name.
+  author: Zhenjia
+  # Canonical site URL (no trailing slash).
+  url: https://zhenjia.org
+  # Base path. Use '/' unless the site is served from a subpath.
+  base: /
+  # Favicon URL. Recommended formats: svg, png, ico.
+  favicon: /icons/favicon.svg
+
+# ---- COLOR ------------------------------------------------------------------
+color:
+  # Default theme mode: light | dark | auto.
+  mode: light
+  light:
+    primary: oklch(25% 0.005 298)
+    secondary: oklch(40% 0.005 298)
+    background: oklch(96% 0.005 298)
+    highlight: oklch(0.93 0.195089 103.2532 / 0.5)
+  dark:
+    primary: oklch(92% 0.005 298)
+    secondary: oklch(77% 0.005 298)
+    background: oklch(22% 0.005 298)
+    highlight: oklch(0.93 0.195089 103.2532 / 0.2)
+
+# ---- GLOBAL -----------------------------------------------------------------
+global:
+  # Default language: de | en | es | fr | ja | ko | pl | pt | ru | zh | zh-tw.
+  locale: zh
+  # Additional languages (do not include the default locale here).
+  moreLocales:
+    - en
+    - ja
+  # Post font style: sans | serif.
+  fontStyle: sans
+  # Date format: YYYY-MM-DD | MM-DD-YYYY | DD-MM-YYYY | MMM D YYYY | D MMM YYYY.
+  dateFormat: YYYY-MM-DD
+  # Enable table of contents.
+  toc: true
+  # Enable KaTeX math rendering.
+  katex: true
+  # Reduce motion.
+  reduceMotion: false
+
+# ---- COMMENT ----------------------------------------------------------------
+comment:
+  # Enable comment system.
+  enabled: false
+  giscus:
+    repo: ''
+    repoId: ''
+    category: ''
+    categoryId: ''
+    mapping: pathname
+    strict: '0'
+    reactionsEnabled: '1'
+    emitMetadata: '0'
+    inputPosition: bottom
+  twikoo:
+    envId: ''
+  waline:
+    serverURL: https://retypeset-comment.radishzz.cc
+    emoji:
+      - https://unpkg.com/@waline/emojis@1.2.0/tw-emoji
+    search: false
+    imageUploader: false
+
+# ---- SEO --------------------------------------------------------------------
+seo:
+  # @twitter ID.
+  twitterID: ''
+  verification:
+    google: ''
+    bing: ''
+    yandex: ''
+    baidu: ''
+  # Google Analytics 4 measurement ID (G-XXXXXXXXXX). Not the legacy UA-* form.
+  googleAnalyticsID: ''
+  # Umami analytics ID (https://cloud.umami.is).
+  umamiAnalyticsID: ''
+  # Follow.is verification.
+  follow:
+    feedID: ''
+    userID: ''
+  # ApiFlash access key (https://apiflash.com/) for generating OG screenshots.
+  apiflashKey: ''
+
+# ---- FOOTER -----------------------------------------------------------------
+footer:
+  links:
+    - name: RSS
+      url: /atom.xml
+    - name: GitHub
+      url: https://github.com/lifeodyssey
+  # Year the site was first published.
+  startYear: 2016
+
+# ---- COLLECTIONS ------------------------------------------------------------
+# Built-in collections (`posts`, `notes`, `journals`) are always enabled by
+# default. Any extra top-level folder under `content/` (e.g. `content/tech/`)
+# becomes its own collection automatically, with `/tech` as the list page and
+# `/tech/<slug>` as the detail page. You can disable any collection by setting
+# `enabled: false`. Folders prefixed with `_` or `.` are ignored, so use
+# `content/_drafts/` for in-progress material.
+collections:
+  posts:
+    enabled: true
+  notes:
+    enabled: true
+  journals:
+    enabled: true
+
+# ---- PRELOAD ----------------------------------------------------------------
+preload:
+  # Image hosting URL. Used to optimize remote images and generate LQIP.
+  imageHostURL: ''
+  # Custom GA proxy endpoint.
+  customGoogleAnalyticsJS: ''
+  # Custom Umami proxy endpoint.
+  customUmamiAnalyticsJS: ''

package/discover-collections.ts

@@ -0,0 +1,160 @@
+/**
+ * Shared folder discovery + collection-enablement resolution.
+ *
+ * Both `integration.ts` and `src/content.config.ts` call into this module so
+ * the set of active collections is computed identically in the two places
+ * (Astro statically loads `content.config.ts` in its own Vite environment,
+ * so we can't share state between them at runtime — but both can read the
+ * same YAML and scan the same `content/` directory).
+ *
+ * Behaviour:
+ *
+ *   - Built-in collections: `posts`, `notes`, `journals` are always
+ *     candidates. They appear in the result unless the consumer explicitly
+ *     sets `collections.<name>.enabled: false` in `retypeset.config.yaml`.
+ *
+ *   - Dynamic collections: every direct child folder of
+ *     `<projectRoot>/content/` that is NOT a built-in, NOT prefixed with `_`
+ *     or `.`, AND has a valid URL-segment name becomes its own collection.
+ *     Each dynamic folder may be opted out the same way (set
+ *     `collections.<folder>.enabled: false`).
+ *
+ *   - When no `content/` directory exists (e.g. fresh checkout of the
+ *     theme repo before any content is wired up), only built-in
+ *     collections are returned and the dynamic-collection list is empty.
+ *
+ * The slug used for both the collection name and the URL segment is the
+ * folder name verbatim. Folders whose name contains characters outside
+ * `[a-zA-Z0-9-]` are skipped with a warning — those would need encoding or
+ * renaming to be safe in URLs and JS identifiers.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { isAbsolute, resolve as resolvePath } from 'node:path'
+import yaml from 'yaml'
+
+export const BUILT_IN_COLLECTIONS = ['posts', 'notes', 'journals'] as const
+export type BuiltInCollection = typeof BUILT_IN_COLLECTIONS[number]
+
+const URL_SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9-]*$/
+
+export interface CollectionDiscovery {
+  /** Enabled built-in collections, in canonical order. */
+  enabledBuiltIns: BuiltInCollection[]
+  /** Dynamic folders that should become collections, in scan order. */
+  dynamicFolders: string[]
+  /** Folders that were skipped because the name is not URL-safe. */
+  skippedFolders: string[]
+}
+
+interface RawCollectionConfig {
+  enabled?: boolean
+}
+
+function readCollectionsSection(
+  projectRoot: string,
+  userConfigPath?: string,
+): Record<string, RawCollectionConfig> {
+  const candidates: string[] = []
+
+  if (userConfigPath) {
+    const abs = isAbsolute(userConfigPath)
+      ? userConfigPath
+      : resolvePath(projectRoot, userConfigPath)
+    candidates.push(abs)
+  }
+  else {
+    candidates.push(resolvePath(projectRoot, 'retypeset.config.yaml'))
+  }
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate))
+      continue
+
+    try {
+      const parsed = yaml.parse(readFileSync(candidate, 'utf-8')) as
+        | { collections?: Record<string, RawCollectionConfig> }
+        | undefined
+      return parsed?.collections ?? {}
+    }
+    catch {
+      // Malformed YAML — fall through to defaults.
+      return {}
+    }
+  }
+
+  return {}
+}
+
+function isEnabled(
+  collectionsConfig: Record<string, RawCollectionConfig>,
+  name: string,
+  defaultEnabled: boolean,
+): boolean {
+  const entry = collectionsConfig[name]
+  if (entry?.enabled === false)
+    return false
+  if (entry?.enabled === true)
+    return true
+  return defaultEnabled
+}
+
+/**
+ * Walk `<projectRoot>/content/` and resolve which collections are active.
+ *
+ * @param projectRoot Consumer project root (or theme root in standalone mode).
+ * @param userConfigPath Optional explicit path to `retypeset.config.yaml`.
+ */
+export function discoverCollections(
+  projectRoot: string,
+  userConfigPath?: string,
+): CollectionDiscovery {
+  const collectionsConfig = readCollectionsSection(projectRoot, userConfigPath)
+  const contentDir = resolvePath(projectRoot, 'content')
+
+  const enabledBuiltIns = BUILT_IN_COLLECTIONS.filter(name =>
+    isEnabled(collectionsConfig, name, true),
+  )
+
+  if (!existsSync(contentDir)) {
+    return { enabledBuiltIns, dynamicFolders: [], skippedFolders: [] }
+  }
+
+  const dynamicFolders: string[] = []
+  const skippedFolders: string[] = []
+
+  for (const entry of readdirSync(contentDir)) {
+    if (entry.startsWith('_') || entry.startsWith('.'))
+      continue
+    if ((BUILT_IN_COLLECTIONS as readonly string[]).includes(entry))
+      continue
+    // `about` lives in src/content/about, but if a consumer puts a top-level
+    // `about` folder in content/ that would collide with the built-in route.
+    // Skip with a warning, the consumer needs to rename it.
+    if (entry === 'about') {
+      skippedFolders.push(entry)
+      continue
+    }
+
+    const fullPath = resolvePath(contentDir, entry)
+    try {
+      if (!statSync(fullPath).isDirectory())
+        continue
+    }
+    catch {
+      continue
+    }
+
+    if (!URL_SAFE_NAME.test(entry)) {
+      skippedFolders.push(entry)
+      continue
+    }
+
+    if (!isEnabled(collectionsConfig, entry, true))
+      continue
+
+    dynamicFolders.push(entry)
+  }
+
+  return { enabledBuiltIns, dynamicFolders, skippedFolders }
+}