@jet-w/astro-blog 0.1.6 → 0.2.1

package/src/plugins/remark-protect-code.mjs

@@ -0,0 +1,69 @@
+/**
+ * Remark plugin to protect code blocks from directive processing
+ * This plugin runs BEFORE other plugins to replace ::: in code blocks
+ * with a placeholder, then a rehype plugin restores them after processing
+ */
+
+// Unique placeholder that won't appear in normal content
+const COLON_PLACEHOLDER = '___TRIPLE_COLON___';
+
+export function remarkProtectCode() {
+  return (tree) => {
+    // Visit all code nodes and replace ::: with placeholder
+    visitCode(tree);
+  };
+}
+
+function visitCode(node) {
+  if (node.type === 'code' && node.value) {
+    // Replace all ::: patterns in code blocks with placeholder
+    node.value = node.value.replace(/:::/g, COLON_PLACEHOLDER);
+  }
+
+  // Recursively visit children
+  if (node.children) {
+    for (const child of node.children) {
+      visitCode(child);
+    }
+  }
+}
+
+/**
+ * Rehype plugin to restore ::: in code blocks after directive processing
+ */
+export function rehypeRestoreCode() {
+  return (tree) => {
+    visitElement(tree);
+  };
+}
+
+function visitElement(node) {
+  // Handle text nodes
+  if (node.type === 'text' && node.value) {
+    node.value = node.value.replace(new RegExp(COLON_PLACEHOLDER, 'g'), ':::');
+  }
+
+  // Handle raw HTML nodes
+  if (node.type === 'raw' && node.value) {
+    node.value = node.value.replace(new RegExp(COLON_PLACEHOLDER, 'g'), ':::');
+  }
+
+  // Handle element nodes with properties (like code elements)
+  if (node.type === 'element') {
+    // Check for text content in code elements
+    if (node.children) {
+      for (const child of node.children) {
+        visitElement(child);
+      }
+    }
+  }
+
+  // Recursively visit children
+  if (node.children) {
+    for (const child of node.children) {
+      visitElement(child);
+    }
+  }
+}
+
+export { COLON_PLACEHOLDER };

package/src/styles/global.css

@@ -248,13 +248,47 @@
   }
 
   .container-details .container-title {
-    @apply text-purple-800 dark:text-purple-200 bg-purple-100 dark:bg-purple-800/30;
+    @apply text-purple-800 dark:text-purple-200 bg-purple-100 dark:bg-purple-800/30 cursor-pointer select-none;
   }
 
   .container-details .container-content {
     @apply text-purple-700 dark:text-purple-300;
   }
 
+  /* details 展开/折叠图标 */
+  .container-details > summary.container-title {
+    @apply list-none relative pr-8;
+  }
+
+  /* 移除默认的三角形图标 (Safari) */
+  .container-details > summary.container-title::-webkit-details-marker {
+    display: none;
+  }
+
+  /* 自定义展开/折叠箭头图标 */
+  .container-details > summary.container-title::after {
+    content: '';
+    @apply absolute right-3 top-1/2 -translate-y-1/2 w-4 h-4 transition-transform duration-200;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%237c3aed' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m9 18 6-6-6-6'/%3E%3C/svg%3E");
+    background-size: contain;
+    background-repeat: no-repeat;
+  }
+
+  /* 深色模式下的箭头颜色 */
+  .dark .container-details > summary.container-title::after {
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24' fill='none' stroke='%23c4b5fd' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m9 18 6-6-6-6'/%3E%3C/svg%3E");
+  }
+
+  /* 展开状态时旋转箭头 */
+  .container-details[open] > summary.container-title::after {
+    transform: translateY(-50%) rotate(90deg);
+  }
+
+  /* 悬停效果 */
+  .container-details > summary.container-title:hover {
+    @apply bg-purple-200 dark:bg-purple-700/40;
+  }
+
   /* 容器内的段落样式 */
   .custom-container .container-content p {
     @apply mb-3 last:mb-0;

package/templates/default/.claude/ralph-loop.local.md

@@ -0,0 +1,48 @@
+---
+active: false
+iteration: 2
+max_iterations: 20
+completion_promise: "DONE"
+started_at: "2026-01-29T01:25:08Z"
+completed_at: "2026-01-29T01:48:00Z"
+---
+
+DONE
+
+## Issue Fixed
+
+The i18n URL routing and navigation link issue has been resolved.
+
+### Root Cause Analysis
+
+When English is set as the default locale with `prefixDefaultLocale: false`:
+- English pages use URLs without prefix: `/posts/...`
+- Chinese pages should use URLs with prefix: `/zh-CN/posts/...`
+
+However, the navigation menu and sidebar tree links in the zh-CN locale config were missing the `/zh-CN/` prefix, causing navigation links to point to the wrong locale.
+
+### Files Modified
+
+1. **`templates/default/src/config/locales/zh-CN/menu.ts`**
+   - Updated all menu links to include `/zh-CN/` prefix
+   - Changed `href: '/'` to `href: '/zh-CN/'`
+   - Changed `href: '/posts/...'` to `href: '/zh-CN/posts/...'`
+   - Changed `href: '/slides'` to `href: '/zh-CN/slides'`
+   - Changed `href: '/about'` to `href: '/zh-CN/about'`
+
+2. **`templates/default/src/config/locales/zh-CN/sidebar.ts`**
+   - Updated sidebar group titles to Chinese: '快速入门', '使用指南', '配置文档'
+   - Updated comments to Chinese
+
+3. **`src/components/layout/Sidebar.astro`**
+   - Fixed all tree links to use `${localePrefix}/posts/...` instead of hardcoded `/posts/...`
+   - This ensures sidebar tree navigation respects the current locale
+
+### URL Behavior (Correct)
+
+| Language | URL Pattern |
+|----------|-------------|
+| English (default) | `/posts/...`, `/slides`, `/about` |
+| Chinese | `/zh-CN/posts/...`, `/zh-CN/slides`, `/zh-CN/about` |
+
+This is the expected behavior with `prefixDefaultLocale: false`.

package/templates/default/astro.config.mjs

@@ -8,17 +8,38 @@ import rehypeKatex from 'rehype-katex';
 import rehypeRaw from 'rehype-raw';
 
 // Import plugins and integration from @jet-w/astro-blog
-import { astroBlog } from '@jet-w/astro-blog';
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
+import { remarkProtectCode, rehypeRestoreCode } from '@jet-w/astro-blog/plugins/remark-protect-code.mjs';
 import { remarkContainers } from '@jet-w/astro-blog/plugins/remark-containers.mjs';
 import { remarkMermaid } from '@jet-w/astro-blog/plugins/remark-mermaid.mjs';
 import { rehypeCleanContainers } from '@jet-w/astro-blog/plugins/rehype-clean-containers.mjs';
 import { rehypeTabs } from '@jet-w/astro-blog/plugins/rehype-tabs.mjs';
 import { rehypeRelativeLinks } from '@jet-w/astro-blog/plugins/rehype-relative-links.mjs';
 
+// Import locale-specific configurations
+import { zhCNConfig } from './src/config/locales/zh-CN';
+import { enConfig } from './src/config/locales/en';
+
+// i18n configuration - supports any number of languages
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'en',
+  locales: [
+    { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+    { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+  ],
+  routing: {
+    prefixDefaultLocale: false, // en (default) uses /posts, zh-CN uses /zh-CN/posts
+  },
+  localeConfigs: {
+    'en': enConfig,
+    'zh-CN': zhCNConfig,
+  },
+});
+
 // https://astro.build/config
 export default defineConfig({
   integrations: [
-    astroBlog(),
+    astroBlog({ i18n: i18nConfig }),
     vue(),
     mdx(),
     tailwind({
@@ -27,9 +48,10 @@ export default defineConfig({
   ],
   markdown: {
     remarkPlugins: [
-      remarkDirective,
+      remarkProtectCode,  // Must run FIRST to protect code blocks
       remarkMath,
-      remarkContainers,
+      remarkDirective,    // Parse ::: syntax into directive nodes
+      remarkContainers,   // Handle container syntax (works with both plain text and directive nodes)
       remarkMermaid,
     ],
     rehypePlugins: [
@@ -38,6 +60,7 @@ export default defineConfig({
       rehypeCleanContainers,
       rehypeTabs,
       rehypeRelativeLinks,
+      rehypeRestoreCode,  // Must run LAST to restore ::: in code blocks
     ],
     shikiConfig: {
       theme: 'github-dark',
@@ -49,5 +72,11 @@ export default defineConfig({
   base: '/',
   build: {
     assets: 'assets'
+  },
+  vite: {
+    resolve: {
+      // Help Vite resolve peer dependencies from injected routes
+      dedupe: ['@astrojs/rss', 'astro']
+    }
   }
 });

package/templates/default/content/posts/blog_docs_en/01.get-started/01-intro.md

@@ -0,0 +1,81 @@
+---
+title: Introduction
+description: What is Astro Blog and why should you use it?
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Introduction
+---
+
+# Introduction
+
+Astro Blog is a **modern blog system** built for developers and content creators who want a fast, beautiful, and feature-rich blogging experience.
+
+## What is Astro Blog?
+
+Astro Blog is built on top of [Astro](https://astro.build), a modern static site generator. It combines:
+
+- **Astro** - For blazing fast static site generation
+- **Vue 3** - For interactive components
+- **Tailwind CSS** - For beautiful, responsive styling
+
+::: tip Static Site Generation
+Your blog is pre-built as static HTML files, meaning:
+- **Instant page loads** - No server processing needed
+- **Better SEO** - Search engines love static content
+- **Easy hosting** - Deploy anywhere (Vercel, Netlify, GitHub Pages)
+:::
+
+## Key Features
+
+### Writing Features
+
+| Feature | Description |
+|---------|-------------|
+| Markdown/MDX | Write in Markdown with component support |
+| Code Highlighting | Beautiful syntax highlighting for 100+ languages |
+| Math Formulas | LaTeX math with KaTeX |
+| Diagrams | Flowcharts and diagrams with Mermaid |
+| Containers | Callouts, tips, warnings, and more |
+| Videos | Embed YouTube, Bilibili, or self-hosted videos |
+
+### System Features
+
+| Feature | Description |
+|---------|-------------|
+| Dark Mode | Toggle between light and dark themes |
+| Responsive | Perfect on desktop, tablet, and mobile |
+| Search | Full-text search across all posts |
+| RSS Feed | Auto-generated RSS for subscribers |
+| SEO | Optimized meta tags and sitemap |
+| i18n | Multi-language support |
+
+## When to Use Astro Blog?
+
+Astro Blog is perfect for:
+
+::: info Good Use Cases
+- **Tech blogs** - Share tutorials and technical knowledge
+- **Personal blogs** - Document your journey and thoughts
+- **Documentation** - Create product or project docs
+- **Portfolios** - Showcase your work with blog posts
+:::
+
+## Tech Stack
+
+::: details View Full Stack
+- **Framework**: [Astro](https://astro.build) v5.x
+- **UI Components**: [Vue 3](https://vuejs.org)
+- **Styling**: [Tailwind CSS](https://tailwindcss.com) v4.x
+- **Code Highlighting**: [Shiki](https://shiki.style)
+- **Math**: [KaTeX](https://katex.org)
+- **Diagrams**: [Mermaid](https://mermaid.js.org)
+- **Icons**: Font Awesome, Material Icons, Remix Icon, Bootstrap Icons
+:::
+
+---
+
+Ready to set up your blog? Continue to [Installation](./02-install).

package/templates/default/content/posts/blog_docs_en/01.get-started/02-install.md

@@ -0,0 +1,137 @@
+---
+title: Installation
+description: Set up your development environment and install Astro Blog
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Installation
+---
+
+# Installation
+
+This guide will help you set up Astro Blog on your computer.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+### Node.js
+
+Node.js 18.x or higher is required.
+
+```bash
+# Check your Node.js version
+node --version
+# Should output: v18.x.x or higher
+```
+
+::: tip Installing Node.js
+If you don't have Node.js, download it from [nodejs.org](https://nodejs.org).
+Choose the **LTS** version for the best stability.
+:::
+
+### Package Manager
+
+npm comes with Node.js. You can also use pnpm or yarn:
+
+```bash
+# Check npm version
+npm --version
+
+# Or use pnpm (recommended for faster installs)
+npm install -g pnpm
+pnpm --version
+```
+
+## Install Dependencies
+
+Navigate to your blog project folder and install dependencies:
+
+```bash
+# Using npm
+npm install
+
+# Or using pnpm
+pnpm install
+```
+
+This will install all required packages defined in `package.json`.
+
+## Start Development Server
+
+Start the local development server:
+
+```bash
+# Using npm
+npm run dev
+
+# Or using pnpm
+pnpm dev
+```
+
+You should see output like:
+
+```
+🚀 astro  v5.x.x ready in 1234ms
+
+┃ Local    http://localhost:4321/
+┃ Network  use --host to expose
+```
+
+::: tip Hot Reload
+The development server supports hot reload. When you save a file, the browser automatically refreshes to show your changes.
+:::
+
+## Open in Browser
+
+Visit `http://localhost:4321` in your browser. You should see your blog's homepage!
+
+## Verify Installation
+
+Check that everything works:
+
+1. **Homepage loads** - You see the blog homepage
+2. **Posts list** - Navigate to `/posts` to see articles
+3. **Dark mode** - Toggle the theme switch in the header
+4. **Search** - Try the search function
+
+## Common Issues
+
+### Port Already in Use
+
+If port 4321 is busy, Astro will use another port. Check the terminal output for the actual URL.
+
+Or specify a different port:
+
+```bash
+npm run dev -- --port 3000
+```
+
+### Dependencies Not Installing
+
+Try clearing the cache:
+
+```bash
+# Remove node_modules and lock file
+rm -rf node_modules package-lock.json
+
+# Reinstall
+npm install
+```
+
+### Node.js Version Too Old
+
+Update Node.js to version 18 or higher. Consider using [nvm](https://github.com/nvm-sh/nvm) to manage Node versions:
+
+```bash
+# Install nvm, then:
+nvm install 20
+nvm use 20
+```
+
+---
+
+Development server running? Great! Let's [create your first post](./03-create-post).

package/templates/default/content/posts/blog_docs_en/01.get-started/03-create-post.md

@@ -0,0 +1,176 @@
+---
+title: Create Your First Post
+description: Write and publish your first blog article
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Getting Started
+  - Writing
+---
+
+# Create Your First Post
+
+Let's write your first blog post! This is where the fun begins.
+
+## Where Posts Live
+
+All blog posts go in the `content/posts/` directory:
+
+```
+content/
+└── posts/
+    ├── my-first-post.md    ← Your posts go here
+    ├── another-post.md
+    └── tech/               ← Or in subdirectories
+        └── tutorial.md
+```
+
+## Create a New Post
+
+Create a file called `hello-world.md` in `content/posts/`:
+
+```markdown
+---
+title: Hello World
+description: My first blog post
+pubDate: 2025-01-15
+author: Your Name
+tags:
+  - Introduction
+categories:
+  - Personal
+---
+
+# Hello World
+
+Welcome to my blog! This is my first post.
+
+## Why I Started Blogging
+
+I started this blog to:
+
+1. Share what I learn
+2. Document my journey
+3. Connect with others
+
+> The best time to start was yesterday. The second best time is now.
+
+## What's Next
+
+Stay tuned for more posts about:
+
+- Web development
+- My projects
+- Lessons learned
+
+Thanks for reading!
+```
+
+## View Your Post
+
+Save the file and visit:
+
+```
+http://localhost:4321/posts/hello-world
+```
+
+Your post should appear with full styling!
+
+## Understanding Frontmatter
+
+The section between `---` markers is called **frontmatter**. It contains metadata about your post:
+
+```yaml
+---
+title: Hello World          # Required - Post title
+description: My first post  # For SEO and previews
+pubDate: 2025-01-15        # Publication date
+author: Your Name          # Author name
+tags:                      # Tags (array)
+  - Introduction
+categories:                # Categories (array)
+  - Personal
+draft: false               # true = hidden from listing
+star: false                # true = featured post
+---
+```
+
+::: tip Required vs Optional
+Only `title` is required. All other fields are optional but recommended for better organization and SEO.
+:::
+
+## Using Subdirectories
+
+Organize related posts in subdirectories:
+
+```
+content/posts/
+├── tutorials/
+│   ├── README.md        ← Shows at /posts/tutorials
+│   ├── javascript.md    ← Shows at /posts/tutorials/javascript
+│   └── css.md           ← Shows at /posts/tutorials/css
+└── projects/
+    └── my-app.md        ← Shows at /posts/projects/my-app
+```
+
+### Directory README
+
+Each directory can have a `README.md` that serves as the directory's index page:
+
+```markdown
+---
+title: Tutorials
+description: Learn web development step by step
+---
+
+# Tutorials
+
+Welcome to my tutorials section!
+
+- [JavaScript Basics](./javascript)
+- [CSS Tricks](./css)
+```
+
+## URL Path Rules
+
+Your file path determines the URL:
+
+| File Path | URL |
+|-----------|-----|
+| `posts/hello.md` | `/posts/hello` |
+| `posts/tech/intro.md` | `/posts/tech/intro` |
+| `posts/tech/README.md` | `/posts/tech` |
+
+::: info Case Insensitive
+URLs are automatically lowercased. `Hello-World.md` becomes `/posts/hello-world`.
+:::
+
+## Adding Images
+
+Place images in `public/images/` and reference them:
+
+```markdown
+![My Photo](/images/photo.jpg)
+```
+
+For post-specific images, you can create a folder:
+
+```
+public/
+└── images/
+    └── posts/
+        └── hello-world/
+            └── cover.jpg
+```
+
+Then use:
+
+```markdown
+![Cover](/images/posts/hello-world/cover.jpg)
+```
+
+---
+
+Congratulations on your first post! Next, let's understand the [project structure](./04-structure).