@jet-w/astro-blog 0.1.5 → 0.2.0

package/templates/default/content/posts/blog_docs_en/config/02-sidebar.md

@@ -0,0 +1,240 @@
+---
+title: Sidebar Configuration
+description: Configure navigation trees and document organization
+pubDate: 2025-01-01
+author: Astro Blog
+categories:
+  - Documentation
+tags:
+  - Configuration
+  - Sidebar
+---
+
+# Sidebar Configuration
+
+The sidebar provides navigation and document organization for your blog.
+
+## Basic Configuration
+
+Edit `src/config/sidebar.ts`:
+
+```typescript
+export const sidebarConfig = {
+  enabled: true,
+  showSearch: true,
+  showRecentPosts: true,
+  recentPostsCount: 5,
+  showPopularTags: true,
+  popularTagsCount: 8,
+  showArchives: true,
+  archivesCount: 6,
+  groups: [],
+};
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Show/hide sidebar |
+| `showSearch` | boolean | `true` | Show search box |
+| `showRecentPosts` | boolean | `true` | Show recent posts |
+| `recentPostsCount` | number | `5` | Number of recent posts |
+| `showPopularTags` | boolean | `true` | Show tag cloud |
+| `popularTagsCount` | number | `8` | Number of tags |
+| `showArchives` | boolean | `true` | Show archives |
+| `archivesCount` | number | `6` | Number of archive months |
+| `groups` | array | `[]` | Document tree groups |
+
+## Document Tree Groups
+
+Groups create organized navigation for specific sections.
+
+### Auto-Scan Groups
+
+Automatically generate navigation from a folder:
+
+```typescript
+// src/config/locales/en/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: 'Documentation',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_en',
+      collapsed: false,
+      showForPaths: ['/posts/blog_docs_en/**'],
+    },
+  ],
+};
+```
+
+| Option | Description |
+|--------|-------------|
+| `type` | `'scan'` for auto-scan |
+| `title` | Group heading |
+| `icon` | Remix icon name |
+| `scanPath` | Folder to scan in `content/posts/` |
+| `collapsed` | Start collapsed |
+| `showForPaths` | Only show on matching URLs |
+
+### Manual Groups
+
+Define navigation manually:
+
+```typescript
+{
+  type: 'manual',
+  title: 'Resources',
+  icon: 'ri:links-line',
+  items: [
+    { title: 'API Reference', slug: 'api-reference' },
+    { title: 'Examples', link: 'https://examples.com' },
+  ],
+  showForPaths: ['/posts/api/**'],
+}
+```
+
+## Path Matching
+
+Control when groups appear with `showForPaths`:
+
+```typescript
+showForPaths: [
+  '/posts/docs/**',     // All docs pages
+  '/posts/tutorials/*', // Direct children only
+  '/about',            // Exact match
+]
+```
+
+### Pattern Syntax
+
+| Pattern | Matches |
+|---------|---------|
+| `/posts/docs` | Exact path |
+| `/posts/docs/*` | Direct children |
+| `/posts/docs/**` | All descendants |
+
+## Per-Language Sidebar
+
+Configure different sidebars for each language:
+
+```typescript
+// src/config/locales/en/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: 'Documentation',  // English
+      scanPath: 'blog_docs_en',
+      showForPaths: ['/posts/blog_docs_en/**'],
+    },
+  ],
+};
+
+// src/config/locales/zh-CN/sidebar.ts
+export const sidebar = {
+  groups: [
+    {
+      type: 'scan',
+      title: '文档',  // Chinese
+      scanPath: 'blog_docs',
+      showForPaths: ['/zh-CN/posts/blog_docs/**'],
+    },
+  ],
+};
+```
+
+## Complete Example
+
+```typescript
+// src/config/locales/en/sidebar.ts
+export const sidebar = {
+  groups: [
+    // Documentation section
+    {
+      type: 'scan',
+      title: 'Documentation',
+      icon: 'ri:book-open-line',
+      scanPath: 'blog_docs_en',
+      collapsed: false,
+      showForPaths: ['/posts/blog_docs_en/**'],
+    },
+    // Tutorials section
+    {
+      type: 'scan',
+      title: 'Tutorials',
+      icon: 'ri:graduation-cap-line',
+      scanPath: 'tutorials',
+      collapsed: true,
+      showForPaths: ['/posts/tutorials/**'],
+    },
+    // External resources
+    {
+      type: 'manual',
+      title: 'Resources',
+      icon: 'ri:links-line',
+      items: [
+        { title: 'Astro Docs', link: 'https://docs.astro.build' },
+        { title: 'Tailwind CSS', link: 'https://tailwindcss.com' },
+      ],
+    },
+  ],
+};
+```
+
+## Sidebar Widgets
+
+The sidebar also shows:
+
+### Recent Posts
+
+Shows latest published posts:
+
+```typescript
+showRecentPosts: true,
+recentPostsCount: 5,
+```
+
+### Popular Tags
+
+Shows most-used tags:
+
+```typescript
+showPopularTags: true,
+popularTagsCount: 8,
+```
+
+### Archives
+
+Shows posts by month:
+
+```typescript
+showArchives: true,
+archivesCount: 6,
+```
+
+## Hiding the Sidebar
+
+Disable sidebar for specific pages in frontmatter:
+
+```yaml
+---
+title: Full Width Page
+showSidebar: false
+---
+```
+
+Or globally:
+
+```typescript
+export const sidebarConfig = {
+  enabled: false,
+  // ...
+};
+```
+
+---
+
+Next: [Multi-language Support](./03-i18n)

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

@@ -0,0 +1,285 @@
+---
+title: Multi-language Support
+description: Add multiple language support to your blog
+pubDate: 2025-01-01
+author: Astro Blog
+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
+└── zh-CN/
+    ├── index.ts
+    ├── site.ts
+    ├── menu.ts
+    ├── footer.ts
+    └── sidebar.ts
+```
+
+### 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';
+
+export const enConfig = {
+  site,
+  menu,
+  footer,
+  sidebar,
+};
+```
+
+**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
+
+Built-in translations for common UI text:
+
+```typescript
+// Already included for en and zh-CN
+const translations = {
+  home: 'Home',
+  posts: 'Posts',
+  tags: 'Tags',
+  readMore: 'Read more',
+  // ... 50+ strings
+};
+```
+
+Override specific strings:
+
+```typescript
+// In your locale config
+export const enConfig = {
+  // ...
+  ui: {
+    readMore: 'Continue reading',
+    // Only override what you need
+  },
+};
+```
+
+## 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
+```
+
+3. Add to `localeConfigs`:
+
+```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/config/README.md

@@ -0,0 +1,85 @@
+---
+title: Configuration
+description: Customize your blog with site settings, sidebar, and i18n
+pubDate: 2025-01-01
+author: Astro Blog
+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/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: Astro Blog
+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).