@jet-w/astro-blog 0.2.0 → 0.2.2

package/templates/default/content/posts/blog_docs_en/{config → 03.config}/02-sidebar.md

@@ -2,7 +2,7 @@
 title: Sidebar Configuration
 description: Configure navigation trees and document organization
 pubDate: 2025-01-01
-author: Astro Blog
+author: jet-w
 categories:
   - Documentation
 tags:

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

@@ -2,7 +2,7 @@
 title: Multi-language Support
 description: Add multiple language support to your blog
 pubDate: 2025-01-01
-author: Astro Blog
+author: jet-w
 categories:
   - Documentation
 tags:
@@ -66,13 +66,15 @@ src/config/locales/
 │   ├── site.ts
 │   ├── menu.ts
 │   ├── footer.ts
-│   └── sidebar.ts
+│   ├── sidebar.ts
+│   └── ui.ts        # UI translations
 └── zh-CN/
     ├── index.ts
     ├── site.ts
     ├── menu.ts
     ├── footer.ts
-    └── sidebar.ts
+    ├── sidebar.ts
+    └── ui.ts        # UI translations
 ```
 
 ### 3. Configure Each Language
@@ -84,12 +86,14 @@ 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,
 };
 ```
 
@@ -190,32 +194,47 @@ Each locale can override:
 
 ## UI Translations
 
-Built-in translations for common UI text:
+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.
 
-```typescript
-// Already included for en and zh-CN
-const translations = {
-  home: 'Home',
-  posts: 'Posts',
-  tags: 'Tags',
-  readMore: 'Read more',
-  // ... 50+ strings
-};
-```
+### Creating UI Translations
 
-Override specific strings:
+**English (`en/ui.ts`):**
 
 ```typescript
-// In your locale config
-export const enConfig = {
-  // ...
-  ui: {
-    readMore: 'Continue reading',
-    // Only override what you need
-  },
+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:
@@ -236,10 +255,55 @@ src/config/locales/ja/
 ├── site.ts
 ├── menu.ts
 ├── footer.ts
-└── sidebar.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',
+};
 ```
 
-3. Add to `localeConfigs`:
+5. Add to `localeConfigs` in `astro.config.mjs`:
 
 ```typescript
 import { jaConfig } from './src/config/locales/ja';

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

@@ -2,7 +2,7 @@
 title: Configuration
 description: Customize your blog with site settings, sidebar, and i18n
 pubDate: 2025-01-01
-author: Astro Blog
+author: jet-w
 categories:
   - Documentation
 tags:

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

@@ -2,7 +2,7 @@
 title: Astro Blog Documentation
 description: A modern blog system built with Astro, Vue, and Tailwind CSS
 pubDate: 2025-01-01
-author: Astro Blog
+author: jet-w
 categories:
   - Documentation
 tags:
@@ -20,6 +20,7 @@ A modern, feature-rich blog system built with **Astro**, **Vue 3**, and **Tailwi
 - **Modern** - Built with the latest web technologies
 - **Flexible** - Markdown, MDX, and rich component support
 - **Beautiful** - Clean design with dark mode support
+
 :::
 
 ## 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)。

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

@@ -0,0 +1,137 @@
+---
+title: 安装
+description: 设置你的开发环境并安装 Astro 博客
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 安装
+---
+
+# 安装
+
+本指南将帮助你在电脑上设置 Astro 博客。
+
+## 前置要求
+
+在开始之前，请确保你已具备：
+
+### Node.js
+
+需要 Node.js 18.x 或更高版本。
+
+```bash
+# 检查你的 Node.js 版本
+node --version
+# 应该输出：v18.x.x 或更高
+```
+
+::: tip 安装 Node.js
+如果你没有 Node.js，请从 [nodejs.org](https://nodejs.org) 下载。
+选择 **LTS** 版本以获得最佳稳定性。
+:::
+
+### 包管理器
+
+npm 随 Node.js 一起安装。你也可以使用 pnpm 或 yarn：
+
+```bash
+# 检查 npm 版本
+npm --version
+
+# 或使用 pnpm（推荐，安装更快）
+npm install -g pnpm
+pnpm --version
+```
+
+## 安装依赖
+
+进入你的博客项目文件夹并安装依赖：
+
+```bash
+# 使用 npm
+npm install
+
+# 或使用 pnpm
+pnpm install
+```
+
+这将安装 `package.json` 中定义的所有必需包。
+
+## 启动开发服务器
+
+启动本地开发服务器：
+
+```bash
+# 使用 npm
+npm run dev
+
+# 或使用 pnpm
+pnpm dev
+```
+
+你应该看到类似这样的输出：
+
+```
+🚀 astro  v5.x.x ready in 1234ms
+
+┃ Local    http://localhost:4321/
+┃ Network  use --host to expose
+```
+
+::: tip 热重载
+开发服务器支持热重载。当你保存文件时，浏览器会自动刷新以显示你的更改。
+:::
+
+## 在浏览器中打开
+
+在浏览器中访问 `http://localhost:4321`。你应该能看到你的博客首页！
+
+## 验证安装
+
+检查一切是否正常工作：
+
+1. **首页加载** - 你看到博客首页
+2. **文章列表** - 导航到 `/posts` 查看文章
+3. **深色模式** - 切换顶部的主题开关
+4. **搜索** - 尝试搜索功能
+
+## 常见问题
+
+### 端口已被占用
+
+如果端口 4321 被占用，Astro 会使用其他端口。检查终端输出获取实际 URL。
+
+或者指定不同的端口：
+
+```bash
+npm run dev -- --port 3000
+```
+
+### 依赖安装失败
+
+尝试清除缓存：
+
+```bash
+# 删除 node_modules 和 lock 文件
+rm -rf node_modules package-lock.json
+
+# 重新安装
+npm install
+```
+
+### Node.js 版本过旧
+
+将 Node.js 更新到 18 或更高版本。考虑使用 [nvm](https://github.com/nvm-sh/nvm) 来管理 Node 版本：
+
+```bash
+# 安装 nvm 后：
+nvm install 20
+nvm use 20
+```
+
+---
+
+开发服务器运行起来了吗？太好了！让我们 [创建你的第一篇文章](./03-create-post)。

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

@@ -0,0 +1,176 @@
+---
+title: 创建第一篇文章
+description: 编写并发布你的第一篇博客文章
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - 文档
+tags:
+  - 入门
+  - 写作
+---
+
+# 创建第一篇文章
+
+让我们来写你的第一篇博客文章！这才是真正有趣的开始。
+
+## 文章存放位置
+
+所有博客文章都放在 `content/posts/` 目录：
+
+```
+content/
+└── posts/
+    ├── my-first-post.md    ← 你的文章放在这里
+    ├── another-post.md
+    └── tech/               ← 或者放在子目录中
+        └── tutorial.md
+```
+
+## 创建新文章
+
+在 `content/posts/` 中创建一个名为 `hello-world.md` 的文件：
+
+```markdown
+---
+title: Hello World
+description: 我的第一篇博客文章
+pubDate: 2025-01-15
+author: 你的名字
+tags:
+  - 介绍
+categories:
+  - 个人
+---
+
+# Hello World
+
+欢迎来到我的博客！这是我的第一篇文章。
+
+## 我为什么开始写博客
+
+我开始写这个博客是为了：
+
+1. 分享我学到的东西
+2. 记录我的旅程
+3. 与他人建立联系
+
+> 最好的开始时间是昨天，其次是现在。
+
+## 接下来
+
+敬请期待更多关于以下内容的文章：
+
+- Web 开发
+- 我的项目
+- 经验教训
+
+感谢阅读！
+```
+
+## 查看你的文章
+
+保存文件后访问：
+
+```
+http://localhost:4321/posts/hello-world
+```
+
+你的文章应该会以完整的样式呈现！
+
+## 理解 Frontmatter
+
+`---` 标记之间的部分称为 **frontmatter**。它包含文章的元数据：
+
+```yaml
+---
+title: Hello World          # 必填 - 文章标题
+description: 我的第一篇文章  # 用于 SEO 和预览
+pubDate: 2025-01-15        # 发布日期
+author: 你的名字            # 作者名称
+tags:                      # 标签（数组）
+  - 介绍
+categories:                # 分类（数组）
+  - 个人
+draft: false               # true = 从列表中隐藏
+star: false                # true = 精选文章
+---
+```
+
+::: tip 必填与可选
+只有 `title` 是必填的。其他字段都是可选的，但建议填写以便更好地组织和优化 SEO。
+:::
+
+## 使用子目录
+
+使用子目录来组织相关文章：
+
+```
+content/posts/
+├── tutorials/
+│   ├── README.md        ← 显示在 /posts/tutorials
+│   ├── javascript.md    ← 显示在 /posts/tutorials/javascript
+│   └── css.md           ← 显示在 /posts/tutorials/css
+└── projects/
+    └── my-app.md        ← 显示在 /posts/projects/my-app
+```
+
+### 目录 README
+
+每个目录可以有一个 `README.md` 作为该目录的索引页面：
+
+```markdown
+---
+title: 教程
+description: 一步步学习 Web 开发
+---
+
+# 教程
+
+欢迎来到我的教程专区！
+
+- [JavaScript 基础](./javascript)
+- [CSS 技巧](./css)
+```
+
+## URL 路径规则
+
+你的文件路径决定了 URL：
+
+| 文件路径 | URL |
+|----------|-----|
+| `posts/hello.md` | `/posts/hello` |
+| `posts/tech/intro.md` | `/posts/tech/intro` |
+| `posts/tech/README.md` | `/posts/tech` |
+
+::: info 大小写不敏感
+URL 会自动转为小写。`Hello-World.md` 变成 `/posts/hello-world`。
+:::
+
+## 添加图片
+
+将图片放在 `public/images/` 目录并引用：
+
+```markdown
+![我的照片](/images/photo.jpg)
+```
+
+对于文章专用的图片，你可以创建一个文件夹：
+
+```
+public/
+└── images/
+    └── posts/
+        └── hello-world/
+            └── cover.jpg
+```
+
+然后使用：
+
+```markdown
+![封面](/images/posts/hello-world/cover.jpg)
+```
+
+---
+
+恭喜你发布了第一篇文章！接下来，让我们了解 [项目结构](./04-structure)。