@jet-w/astro-blog 0.1.6 → 0.2.1

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

@@ -0,0 +1,208 @@
+---
+title: Site Settings
+description: Configure your site's title, description, and metadata
+pubDate: 2025-01-01
+author: jet-w
+categories:
+  - Documentation
+tags:
+  - Configuration
+  - Site
+---
+
+# Site Settings
+
+Configure your blog's basic information and metadata.
+
+## Site Configuration
+
+### Basic Settings
+
+Edit `src/config/site.ts`:
+
+```typescript
+export const siteConfig = {
+  // Site title (shown in browser tab and header)
+  title: 'My Awesome Blog',
+
+  // Site description (used for SEO)
+  description: 'A blog about web development and technology',
+
+  // Author name
+  author: 'John Doe',
+
+  // Author avatar (shown in header and footer)
+  avatar: '/images/avatar.jpg',
+
+  // Site URL (for SEO and RSS)
+  url: 'https://myblog.com',
+};
+```
+
+### Per-Language Settings
+
+For multi-language sites, configure in locale folders:
+
+```typescript
+// src/config/locales/en/site.ts
+export const site = {
+  title: 'My Blog',
+  description: 'A tech blog about web development',
+};
+
+// src/config/locales/zh-CN/site.ts
+export const site = {
+  title: '我的博客',
+  description: '关于 Web 开发的技术博客',
+};
+```
+
+## Navigation Menu
+
+### Menu Configuration
+
+```typescript
+// src/config/locales/en/menu.ts
+export const menu = [
+  { name: 'Home', href: '/', icon: 'home' },
+  { name: 'Posts', href: '/posts', icon: 'posts' },
+  { name: 'Tags', href: '/tags', icon: 'tags' },
+  { name: 'About', href: '/about', icon: 'about' },
+];
+```
+
+### Available Icons
+
+| Icon | Name |
+|------|------|
+| Home icon | `home` |
+| Posts icon | `posts` |
+| Tags icon | `tags` |
+| Categories icon | `categories` |
+| Archives icon | `archives` |
+| Slides icon | `slides` |
+| About icon | `about` |
+
+### External Links
+
+```typescript
+{
+  name: 'GitHub',
+  href: 'https://github.com/username',
+  icon: 'github',
+  external: true  // Opens in new tab
+}
+```
+
+## Social Links
+
+Configure social media links in `src/config/social.ts`:
+
+```typescript
+export const socialLinks = [
+  {
+    type: 'github',
+    url: 'https://github.com/username',
+    label: 'GitHub',
+  },
+  {
+    type: 'twitter',
+    url: 'https://twitter.com/username',
+    label: 'Twitter',
+  },
+  {
+    type: 'email',
+    url: 'mailto:hello@example.com',
+    label: 'Email',
+  },
+];
+```
+
+### Supported Platforms
+
+| Type | Platform |
+|------|----------|
+| `github` | GitHub |
+| `twitter` | Twitter/X |
+| `linkedin` | LinkedIn |
+| `email` | Email |
+| `youtube` | YouTube |
+| `discord` | Discord |
+| `rss` | RSS Feed |
+
+## Footer Configuration
+
+```typescript
+// src/config/locales/en/footer.ts
+export const footer = {
+  quickLinksTitle: 'Quick Links',
+  quickLinks: [
+    { name: 'Home', href: '/' },
+    { name: 'Posts', href: '/posts' },
+    { name: 'About', href: '/about' },
+  ],
+  contactTitle: 'Contact',
+};
+```
+
+## Astro Configuration
+
+Main configuration in `astro.config.mjs`:
+
+```javascript
+export default defineConfig({
+  // Your site's URL (required for RSS and sitemap)
+  site: 'https://myblog.com',
+
+  // Base path if not at root
+  base: '/',
+
+  integrations: [
+    astroBlog({ i18n: i18nConfig }),
+    vue(),
+    tailwind(),
+  ],
+});
+```
+
+## SEO Settings
+
+SEO is configured through:
+
+1. **Site config** - Default title and description
+2. **Frontmatter** - Per-post title and description
+3. **Auto-generated** - Meta tags, Open Graph, Twitter cards
+
+### Default SEO
+
+```typescript
+// src/config/site.ts
+export const defaultSEO = {
+  title: 'My Blog',
+  description: 'Default description for pages',
+  image: '/images/og-default.jpg',
+};
+```
+
+### Per-Post SEO
+
+```yaml
+---
+title: Post Title
+description: Post description for search results
+image: /images/post-cover.jpg
+---
+```
+
+## Best Practices
+
+::: tip Configuration Tips
+1. **Keep URLs consistent** - Use trailing slashes or not, but be consistent
+2. **Optimize images** - Avatar and OG images should be web-optimized
+3. **Write good descriptions** - 150-160 characters for SEO
+4. **Update social links** - Keep them current and working
+:::
+
+---
+
+Next: [Sidebar Configuration](./02-sidebar)

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

@@ -0,0 +1,240 @@
+---
+title: Sidebar Configuration
+description: Configure navigation trees and document organization
+pubDate: 2025-01-01
+author: jet-w
+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)