@jet-w/astro-blog 0.1.6 → 0.2.1

package/templates/default/content/posts/blog_docs_en/03.config/03-i18n.md

@@ -0,0 +1,349 @@
+---
+title: Multi-language Support
+description: Add multiple language support to your blog
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Configuration
+  - i18n
+---
+
+# Multi-language Support
+
+Add support for multiple languages to reach a global audience.
+
+## Overview
+
+The i18n system provides:
+
+- **Multiple languages** - Support any number of languages
+- **URL prefixes** - `/en/posts`, `/zh-CN/posts`
+- **Per-language config** - Different menus, titles, etc.
+- **Language switcher** - Built-in UI component
+- **SEO** - Proper hreflang tags
+
+## Basic Setup
+
+### 1. Configure Languages
+
+In `astro.config.mjs`:
+
+```javascript
+import { astroBlog, defineI18nConfig } from '@jet-w/astro-blog';
+import { enConfig } from './src/config/locales/en';
+import { zhCNConfig } from './src/config/locales/zh-CN';
+
+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,
+  },
+  localeConfigs: {
+    'en': enConfig,
+    'zh-CN': zhCNConfig,
+  },
+});
+
+export default defineConfig({
+  integrations: [astroBlog({ i18n: i18nConfig })],
+});
+```
+
+### 2. Create Locale Configs
+
+Create folders for each language:
+
+```
+src/config/locales/
+├── en/
+│   ├── index.ts
+│   ├── site.ts
+│   ├── menu.ts
+│   ├── footer.ts
+│   ├── sidebar.ts
+│   └── ui.ts        # UI translations
+└── zh-CN/
+    ├── index.ts
+    ├── site.ts
+    ├── menu.ts
+    ├── footer.ts
+    ├── sidebar.ts
+    └── ui.ts        # UI translations
+```
+
+### 3. Configure Each Language
+
+**English (`en/index.ts`):**
+
+```typescript
+import { site } from './site';
+import { menu } from './menu';
+import { footer } from './footer';
+import { sidebar } from './sidebar';
+import { ui } from './ui';
+
+export const enConfig = {
+  site,
+  menu,
+  footer,
+  sidebar,
+  ui,
+};
+```
+
+**English site (`en/site.ts`):**
+
+```typescript
+export const site = {
+  title: 'My Blog',
+  description: 'A blog about technology',
+};
+```
+
+**English menu (`en/menu.ts`):**
+
+```typescript
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+## URL Structure
+
+With `prefixDefaultLocale: false`:
+
+| Language | URL |
+|----------|-----|
+| English (default) | `/posts` |
+| Chinese | `/zh-CN/posts` |
+
+With `prefixDefaultLocale: true`:
+
+| Language | URL |
+|----------|-----|
+| English | `/en/posts` |
+| Chinese | `/zh-CN/posts` |
+
+## Content Organization
+
+### Option 1: Separate Folders
+
+Create separate content folders per language:
+
+```
+content/posts/
+├── blog_docs_en/    # English docs
+│   └── ...
+└── blog_docs/       # Chinese docs
+    └── ...
+```
+
+### Option 2: Same Content
+
+Use the same content with language-aware frontmatter:
+
+```yaml
+---
+title: Hello World
+lang: en
+---
+```
+
+## Language Switcher
+
+The language switcher appears in the header automatically when multiple languages are configured.
+
+It shows:
+- Current language flag/name
+- Dropdown with all languages
+- Links to the same page in other languages
+
+## Locale Configuration Options
+
+### Locale Definition
+
+```typescript
+{
+  code: 'en',           // URL prefix
+  name: 'English',      // Display name
+  htmlLang: 'en',       // HTML lang attribute
+  dateLocale: 'en-US',  // Date formatting
+  direction: 'ltr',     // Text direction (ltr/rtl)
+}
+```
+
+### Per-Locale Config
+
+Each locale can override:
+
+| Config | Purpose |
+|--------|---------|
+| `site` | Title, description, author |
+| `menu` | Navigation links |
+| `footer` | Footer links and text |
+| `sidebar` | Document tree groups |
+| `ui` | UI translation strings |
+
+## UI Translations
+
+The blog includes built-in translations for 50+ UI strings in English and Chinese. You can override any string in your locale's `ui.ts` file.
+
+### Creating UI Translations
+
+**English (`en/ui.ts`):**
+
+```typescript
+import type { UITranslations } from '@jet-w/astro-blog';
+
+export const ui: Partial<UITranslations> = {
+  // Override any UI strings here
+  browsePosts: 'Browse Posts',
+  aboutMe: 'About Me',
+  searchPlaceholder: 'Search articles...',
+  readMore: 'Continue reading',
+};
+```
+
+### Available UI Keys
+
+| Category | Keys |
+|----------|------|
+| Navigation | `home`, `blog`, `about`, `search` |
+| Posts | `posts`, `postList`, `noPostsFound`, `readMore`, `readingTime`, `minuteRead` |
+| Tags & Categories | `tags`, `categories`, `allTags`, `allCategories`, `taggedWith`, `inCategory` |
+| Archives | `archives`, `postsInArchive` |
+| Sidebar | `recentPosts`, `popularTags`, `friendLinks`, `documentTree` |
+| Footer | `quickLinks`, `contact` |
+| Search | `searchPlaceholder`, `searchResults`, `noResults`, `searching`, `searchArticles`, `searchTips`, etc. |
+| Hero | `browsePosts`, `aboutMe` |
+| Pagination | `previousPage`, `nextPage`, `page`, `of` |
+| Article | `publishedOn`, `updatedOn`, `author`, `tableOfContents`, `relatedPosts`, `sharePost` |
+| Misc | `backToTop`, `copyCode`, `copied`, `expand`, `collapse`, `viewMode`, `sortBy`, `draft` |
+| Slides | `slides`, `slidesList` |
+| RSS | `rssFeed` |
+
+::: tip Tip
+
+You only need to override strings you want to customize. The library provides sensible defaults for all strings.
+:::
+
+## Adding a New Language
+
+1. Add to `locales` array:
+
+```typescript
+locales: [
+  { code: 'en', name: 'English', htmlLang: 'en', dateLocale: 'en-US' },
+  { code: 'zh-CN', name: '中文', htmlLang: 'zh-CN', dateLocale: 'zh-CN' },
+  { code: 'ja', name: '日本語', htmlLang: 'ja', dateLocale: 'ja-JP' },  // New
+],
+```
+
+2. Create config folder:
+
+```
+src/config/locales/ja/
+├── index.ts
+├── site.ts
+├── menu.ts
+├── footer.ts
+├── sidebar.ts
+└── ui.ts          # UI translations
+```
+
+3. Create `ui.ts` with translations:
+
+```typescript
+import type { UITranslations } from '@jet-w/astro-blog';
+
+export const ui: Partial<UITranslations> = {
+  // Navigation
+  home: 'ホーム',
+  posts: '記事',
+  tags: 'タグ',
+  categories: 'カテゴリー',
+  search: '検索',
+
+  // Hero section
+  browsePosts: '記事を見る',
+  aboutMe: '私について',
+
+  // Search
+  searchPlaceholder: '記事を検索...',
+  noResults: '結果が見つかりません',
+
+  // Add more translations as needed...
+};
+```
+
+4. Create `index.ts`:
+
+```typescript
+import { site } from './site';
+import { menu } from './menu';
+import { footer } from './footer';
+import { sidebar } from './sidebar';
+import { ui } from './ui';
+
+export const jaConfig = {
+  site,
+  menu,
+  footer,
+  sidebar,
+  ui,
+  contentPathPrefix: 'blog_docs_ja',
+};
+```
+
+5. Add to `localeConfigs` in `astro.config.mjs`:
+
+```typescript
+import { jaConfig } from './src/config/locales/ja';
+
+localeConfigs: {
+  'en': enConfig,
+  'zh-CN': zhCNConfig,
+  'ja': jaConfig,  // New
+},
+```
+
+## RTL Languages
+
+For right-to-left languages (Arabic, Hebrew):
+
+```typescript
+{
+  code: 'ar',
+  name: 'العربية',
+  htmlLang: 'ar',
+  dateLocale: 'ar-SA',
+  direction: 'rtl',  // Enable RTL
+}
+```
+
+## Best Practices
+
+::: tip i18n Tips
+1. **Start with two languages** - Don't add more until needed
+2. **Keep content in sync** - Update all translations together
+3. **Use consistent URLs** - Match URL structure across languages
+4. **Test thoroughly** - Check all pages in all languages
+:::
+
+::: warning Path Consistency
+When changing `defaultLocale`, update all menu and footer links to match the new URL structure.
+:::
+
+---
+
+Congratulations! You've completed the configuration guide.
+
+Return to the [Documentation Home](../) for more topics.

package/templates/default/content/posts/blog_docs_en/03.config/README.md

@@ -0,0 +1,85 @@
+---
+title: Configuration
+description: Customize your blog with site settings, sidebar, and i18n
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Configuration
+  - Settings
+---
+
+# Configuration
+
+Customize every aspect of your blog through configuration files.
+
+## Configuration Files
+
+All configuration lives in `src/config/`:
+
+```
+src/config/
+├── locales/          # Language-specific configs
+│   ├── en/          # English
+│   └── zh-CN/       # Chinese
+├── site.ts           # Site metadata
+├── menu.ts           # Navigation menu
+├── sidebar.ts        # Sidebar settings
+├── footer.ts         # Footer content
+└── social.ts         # Social links
+```
+
+## Configuration Guides
+
+| Guide | Description |
+|-------|-------------|
+| [Site Settings](./01-site) | Title, description, author info |
+| [Sidebar](./02-sidebar) | Navigation and document trees |
+| [Multi-language](./03-i18n) | Add multiple language support |
+
+## Quick Overview
+
+### Site Configuration
+
+```typescript
+// src/config/site.ts
+export const siteConfig = {
+  title: 'My Blog',
+  description: 'A tech blog',
+  author: 'Your Name',
+  avatar: '/images/avatar.jpg',
+};
+```
+
+### Navigation Menu
+
+```typescript
+// src/config/locales/en/menu.ts
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+### Multi-language
+
+```javascript
+// astro.config.mjs
+const i18nConfig = defineI18nConfig({
+  defaultLocale: 'en',
+  locales: [
+    { code: 'en', name: 'English' },
+    { code: 'zh-CN', name: '中文' },
+  ],
+  localeConfigs: {
+    'en': enConfig,
+    'zh-CN': zhCNConfig,
+  },
+});
+```
+
+---
+
+Start with [Site Settings](./01-site)!

package/templates/default/content/posts/blog_docs_en/README.md

@@ -0,0 +1,79 @@
+---
+title: Astro Blog Documentation
+description: A modern blog system built with Astro, Vue, and Tailwind CSS
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Astro
+  - Guide
+star: true
+---
+
+# Astro Blog
+
+A modern, feature-rich blog system built with **Astro**, **Vue 3**, and **Tailwind CSS**.
+
+::: tip Why Choose This Blog?
+- **Fast** - Static site generation with near-instant page loads
+- **Modern** - Built with the latest web technologies
+- **Flexible** - Markdown, MDX, and rich component support
+- **Beautiful** - Clean design with dark mode support
+
+:::
+
+## Get Started
+
+New to Astro Blog? Start here:
+
+| Chapter | Description |
+|---------|-------------|
+| [Introduction](./get-started/) | What is Astro Blog and why use it |
+| [Installation](./get-started/02-install) | Set up your development environment |
+| [First Post](./get-started/03-create-post) | Create and publish your first article |
+| [Project Structure](./get-started/04-structure) | Understand the file organization |
+| [Deployment](./get-started/05-deploy) | Build and deploy your blog |
+
+## Writing Guide
+
+Learn how to write beautiful content:
+
+| Guide | Description |
+|-------|-------------|
+| [Markdown Basics](./guide/markdown/) | Essential Markdown syntax |
+| [Containers](./guide/markdown/02-containers) | Tips, warnings, and callouts |
+| [Code Blocks](./guide/markdown/03-code-blocks) | Syntax highlighting and more |
+| [Diagrams](./guide/features/01-mermaid) | Flowcharts and diagrams with Mermaid |
+| [Math Formulas](./guide/features/02-latex) | LaTeX math rendering |
+| [Videos](./guide/features/03-video) | Embed YouTube, Bilibili, and more |
+| [Icons](./guide/features/04-icons) | Use icons from multiple libraries |
+
+## Configuration
+
+Customize your blog:
+
+| Config | Description |
+|--------|-------------|
+| [Site Settings](./config/01-site) | Title, description, and metadata |
+| [Sidebar](./config/02-sidebar) | Navigation and document trees |
+| [Multi-language](./config/03-i18n) | Add multiple language support |
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+
+# Build for production
+npm run build
+```
+
+Then visit `http://localhost:4321` to see your blog!
+
+---
+
+Ready to begin? Start with the [Introduction](./get-started/)!

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

@@ -0,0 +1,81 @@
+---
+title: 介绍
+description: 什么是 Astro 博客？为什么要使用它？
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 介绍
+---
+
+# 介绍
+
+Astro 博客是一个为开发者和内容创作者打造的**现代博客系统**，提供快速、美观且功能丰富的写作体验。
+
+## 什么是 Astro 博客？
+
+Astro 博客基于 [Astro](https://astro.build) 构建，这是一个现代静态站点生成器。它结合了：
+
+- **Astro** - 闪电般快速的静态站点生成
+- **Vue 3** - 用于交互组件
+- **Tailwind CSS** - 美观、响应式的样式
+
+::: tip 静态站点生成
+你的博客被预先构建为静态 HTML 文件，这意味着：
+- **即时页面加载** - 无需服务器处理
+- **更好的 SEO** - 搜索引擎喜欢静态内容
+- **易于托管** - 可部署到任何地方（Vercel、Netlify、GitHub Pages）
+:::
+
+## 核心特性
+
+### 写作功能
+
+| 特性 | 描述 |
+|------|------|
+| Markdown/MDX | 使用 Markdown 写作，支持组件 |
+| 代码高亮 | 100+ 种语言的精美语法高亮 |
+| 数学公式 | 使用 KaTeX 渲染 LaTeX 数学公式 |
+| 图表 | 使用 Mermaid 绘制流程图和图表 |
+| 容器 | 标注、提示、警告等 |
+| 视频 | 嵌入 YouTube、Bilibili 或自托管视频 |
+
+### 系统功能
+
+| 特性 | 描述 |
+|------|------|
+| 深色模式 | 切换浅色和深色主题 |
+| 响应式 | 完美适配桌面、平板和手机 |
+| 搜索 | 全文搜索所有文章 |
+| RSS 订阅 | 自动生成 RSS 供订阅者使用 |
+| SEO | 优化的 meta 标签和站点地图 |
+| 多语言 | 多语言支持 |
+
+## 何时使用 Astro 博客？
+
+Astro 博客非常适合：
+
+::: info 适用场景
+- **技术博客** - 分享教程和技术知识
+- **个人博客** - 记录你的旅程和想法
+- **文档站点** - 创建产品或项目文档
+- **作品集** - 展示你的作品
+:::
+
+## 技术栈
+
+::: details 查看完整技术栈
+- **框架**: [Astro](https://astro.build) v5.x
+- **UI 组件**: [Vue 3](https://vuejs.org)
+- **样式**: [Tailwind CSS](https://tailwindcss.com) v4.x
+- **代码高亮**: [Shiki](https://shiki.style)
+- **数学**: [KaTeX](https://katex.org)
+- **图表**: [Mermaid](https://mermaid.js.org)
+- **图标**: Font Awesome、Material Icons、Remix Icon、Bootstrap Icons
+:::
+
+---
+
+准备好设置你的博客了吗？继续阅读 [安装](./02-install)。