@x-wave/blog 2.0.0 → 2.1.0

package/vite-config/setup-ssg.ts

@@ -0,0 +1,105 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { PluginOption } from 'vite'
+import { discoverBlogPosts } from './blog-discovery.ts'
+import type { MetaTagsOptions } from './meta-tags.ts'
+import { createStaticGenPlugin } from './static-gen-plugin.ts'
+
+export interface SetupSSGOptions {
+	/** Path to the docs directory (e.g., 'src/docs') */
+	docsPath: string
+	/** Output directory for generated static pages (default: 'dist/docs') */
+	outputDir?: string
+	/** Meta tags configuration */
+	metaTagsOptions?: MetaTagsOptions
+}
+
+/**
+ * Read all MDX files from a docs directory
+ * @param docsDir - Path to the docs directory
+ * @returns Object mapping file paths to content loaders
+ */
+function readMdxFiles(docsDir: string): Record<string, () => Promise<string>> {
+	const mdxFiles: Record<string, () => Promise<string>> = {}
+
+	function walkDir(dir: string, relativePath = '') {
+		if (!fs.existsSync(dir)) return
+
+		const files = fs.readdirSync(dir)
+
+		for (const file of files) {
+			const fullPath = path.join(dir, file)
+			const relPath = path.join(relativePath, file)
+			const stat = fs.statSync(fullPath)
+
+			if (stat.isDirectory()) {
+				walkDir(fullPath, relPath)
+			} else if (file.endsWith('.mdx')) {
+				// Create a lazy loader function
+				mdxFiles[path.join(docsDir, relPath)] = async () =>
+					fs.readFileSync(fullPath, 'utf-8')
+			}
+		}
+	}
+
+	walkDir(docsDir)
+	return mdxFiles
+}
+
+/**
+ * Setup static site generation for blog posts
+ *
+ * This is a convenience function that handles the entire SSG setup process.
+ * It discovers blog posts from your docs directory and creates a Vite plugin.
+ *
+ * @example
+ * ```typescript
+ * import { setupSSG } from '@x-wave/blog/vite-config'
+ *
+ * export default defineConfig(async (env) => {
+ *   const ssgPlugin = env.command === 'build'
+ *     ? await setupSSG({
+ *         docsPath: 'src/docs',
+ *         outputDir: 'dist/docs',
+ *         metaTagsOptions: {
+ *           baseUrl: 'https://example.com',
+ *           siteName: 'My Documentation',
+ *         }
+ *       })
+ *     : undefined
+ *
+ *   return {
+ *     plugins: [react(), ssgPlugin].filter(Boolean),
+ *     // ... rest of config
+ *   }
+ * })
+ * ```
+ */
+export async function setupSSG(
+	options: SetupSSGOptions,
+): Promise<PluginOption | undefined> {
+	try {
+		const { docsPath, outputDir = 'dist/docs', metaTagsOptions = {} } = options
+
+		const mdxFiles = readMdxFiles(docsPath)
+		const { posts } = await discoverBlogPosts(mdxFiles, {
+			blogContentPath: docsPath,
+		})
+
+		if (posts.length === 0) {
+			console.log('📝 No blog posts found, SSG disabled')
+			return undefined
+		}
+
+		console.log(`📝 Discovered ${posts.length} blog posts for SSG`)
+
+		return createStaticGenPlugin({
+			posts,
+			outputDir,
+			metaTagsOptions,
+		})
+	} catch (error) {
+		console.warn('⚠️  SSG initialization failed:', error)
+		return undefined
+	}
+}

package/vite-config/static-gen-plugin.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { Plugin } from 'vite'
+import { generateHtmlWithMetaTags, type MetaTagsOptions } from './meta-tags.ts'
+import type { BlogPostMetadata, BlogSSGConfig } from './types.ts'
+
+export interface StaticGenPluginOptions extends BlogSSGConfig {
+	/** Blog posts to generate static pages for */
+	posts: BlogPostMetadata[]
+	/** Meta tag generation options */
+	metaTagsOptions?: MetaTagsOptions
+	/** Reference to original index.html path */
+	indexHtmlPath?: string
+}
+
+/**
+ * Vite plugin for static site generation of blog posts
+ *
+ * Generates individual HTML files for each blog post with injected meta tags
+ * These files are created after the main build completes
+ */
+export function createStaticGenPlugin(options: StaticGenPluginOptions): Plugin {
+	let config: any
+	const {
+		posts,
+		outputDir = 'dist/docs',
+		metaTagsOptions = {},
+		indexHtmlPath = 'index.html',
+	} = options
+
+	return {
+		name: 'vite-plugin-blog-static-gen',
+
+		configResolved(resolvedConfig) {
+			config = resolvedConfig
+		},
+
+		async generateBundle() {
+			// This hook runs during the bundle generation phase
+			// We'll actually write files in writeBundle to ensure index.html exists
+		},
+
+		async writeBundle() {
+			if (!posts || posts.length === 0) {
+				console.log('📝 No blog posts to generate static files for')
+				return
+			}
+
+			try {
+				// Read the generated index.html
+				const indexHtmlPath_ = path.resolve(config.build.outDir, 'index.html')
+				if (!fs.existsSync(indexHtmlPath_)) {
+					console.warn(
+						`⚠️  Index HTML not found at ${indexHtmlPath_}, skipping static generation`,
+					)
+					return
+				}
+
+				const indexHtmlContent = fs.readFileSync(indexHtmlPath_, 'utf-8')
+
+				console.log(
+					`📝 Generating static pages for ${posts.length} blog posts...`,
+				)
+
+				// Create static HTML file for each blog post
+				for (const post of posts) {
+					const htmlWithMeta = generateHtmlWithMetaTags(
+						indexHtmlContent,
+						post,
+						metaTagsOptions,
+					)
+
+					// Create directory structure: dist/docs/[language]/[slug]/index.html
+					const postDir = path.resolve(
+						config.build.outDir,
+						post.language,
+						post.slug,
+					)
+
+					fs.mkdirSync(postDir, { recursive: true })
+
+					// Write the static HTML file
+					const htmlPath = path.resolve(postDir, 'index.html')
+					fs.writeFileSync(htmlPath, htmlWithMeta, 'utf-8')
+
+					console.log(`  ✓ Generated ${post.language}/${post.slug}/`)
+				}
+
+				console.log(
+					`✨ Static generation complete for ${posts.length} blog posts`,
+				)
+			} catch (error) {
+				console.error('❌ Error generating static blog posts:', error)
+				throw error
+			}
+		},
+	}
+}

package/vite-config/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared types for blog SSG functionality
+ */
+
+export interface BlogPostMetadata {
+	slug: string
+	title: string
+	description?: string
+	ogImage?: string
+	keywords?: string[] | string
+	date?: string
+	author?: string
+	language: string
+	filePath: string
+}
+
+export interface BlogDiscoveryResult {
+	posts: BlogPostMetadata[]
+	postsByLanguage: Record<string, BlogPostMetadata[]>
+	postsBySlug: Record<string, BlogPostMetadata>
+}
+
+export interface BlogSSGConfig {
+	/** Path to blog MDX files relative to app root */
+	blogContentPath?: string
+	/** Whether to generate static files */
+	generateStatic?: boolean
+	/** Output directory for generated blog posts */
+	outputDir?: string
+	/** Base path for blog routes */
+	basePath?: string
+}