@x-wave/blog 1.1.4 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-wave/blog",
-  "version": "1.1.4",
+  "version": "2.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -19,6 +19,10 @@
       "import": "./types/index.js",
       "types": "./types/index.d.ts"
     },
+    "./vite-config": {
+      "import": "./vite-config/index.ts",
+      "types": "./vite-config/index.ts"
+    },
     "./styles": {
       "import": "./styles/index.css"
     }

package/vite-config/blog-discovery.ts

@@ -0,0 +1,160 @@
+import path from 'node:path'
+import type {
+	BlogDiscoveryResult,
+	BlogPostMetadata,
+	BlogSSGConfig,
+} from './types.ts'
+
+/**
+ * Parse YAML frontmatter from MDX content
+ */
+function parseFrontmatter(content: string): Record<string, unknown> {
+	const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n/)
+
+	if (!match) return {}
+
+	const frontmatter: Record<string, unknown> = {}
+	const frontmatterText = match[1]
+	let currentKey = ''
+	let isArrayContext = false
+	const arrayValues: string[] = []
+
+	for (const line of frontmatterText.split('\n')) {
+		const trimmed = line.trim()
+
+		// Handle array items (lines starting with -)
+		if (trimmed.startsWith('-')) {
+			if (isArrayContext) {
+				const value = trimmed.substring(1).trim()
+				arrayValues.push(value)
+			}
+			continue
+		}
+
+		// If we were in array context and hit a non-array line, save the array
+		if (isArrayContext && !trimmed.startsWith('-')) {
+			frontmatter[currentKey] = arrayValues.slice()
+			arrayValues.length = 0
+			isArrayContext = false
+		}
+
+		// Handle key-value pairs
+		if (trimmed?.includes(':')) {
+			const [key, ...valueParts] = trimmed.split(':')
+			const value = valueParts.join(':').trim()
+			currentKey = key.trim()
+
+			// If value is empty, this might be an array declaration
+			if (!value) {
+				isArrayContext = true
+				continue
+			}
+
+			// Parse boolean values
+			if (value === 'true') frontmatter[currentKey] = true
+			else if (value === 'false') frontmatter[currentKey] = false
+			else frontmatter[currentKey] = value
+		}
+	}
+
+	// Save any remaining array
+	if (isArrayContext) {
+		frontmatter[currentKey] = arrayValues.slice()
+	}
+
+	return frontmatter
+}
+
+/**
+ * Extract language from file path based on doc structure
+ * Expected: docs/[language]/[slug].mdx
+ */
+function extractLanguageFromPath(filePath: string): string {
+	const match = filePath.match(/\/docs\/([a-z]{2})\//)
+	return match ? match[1] : 'en'
+}
+
+/**
+ * Extract slug from file path
+ * Expected: docs/[language]/[slug].mdx
+ */
+function extractSlugFromPath(filePath: string): string {
+	const match = filePath.match(/\/([a-z0-9-]+)\.mdx$/)
+	return match ? match[1] : ''
+}
+
+/**
+ * Discover all blog posts from Vite glob import
+ *
+ * @param mdxFiles - Object from import.meta.glob('./docs/**\/*.mdx', { query: '?raw', import: 'default', eager: false })
+ * @param config - SSG configuration options
+ * @returns Collection of discovered blog posts organized by language and slug
+ */
+export async function discoverBlogPosts(
+	mdxFiles: Record<string, () => Promise<unknown>>,
+	config: BlogSSGConfig = {},
+): Promise<BlogDiscoveryResult> {
+	const posts: BlogPostMetadata[] = []
+	const postsByLanguage: Record<string, BlogPostMetadata[]> = {}
+	const postsBySlug: Record<string, BlogPostMetadata> = {}
+
+	// Iterate through all MDX files
+	for (const [filePath, getContent] of Object.entries(mdxFiles)) {
+		try {
+			// Load content
+			const content = (await getContent()) as string
+
+			// Extract language and slug
+			const language = extractLanguageFromPath(filePath)
+			const slug = extractSlugFromPath(filePath)
+
+			if (!slug) continue
+
+			// Parse frontmatter
+			const frontmatter = parseFrontmatter(content)
+
+			// Create metadata object
+			const metadata: BlogPostMetadata = {
+				slug,
+				title: (frontmatter.title as string) || slug,
+				description: frontmatter.description as string | undefined,
+				ogImage: frontmatter.ogImage as string | undefined,
+				keywords: frontmatter.keywords as string[] | string | undefined,
+				date: frontmatter.date as string | undefined,
+				author: frontmatter.author as string | undefined,
+				language,
+				filePath,
+			}
+
+			posts.push(metadata)
+
+			// Index by language
+			if (!postsByLanguage[language]) {
+				postsByLanguage[language] = []
+			}
+			postsByLanguage[language].push(metadata)
+
+			// Index by slug (use [language-slug] composite key to avoid conflicts)
+			postsBySlug[`${language}:${slug}`] = metadata
+		} catch (error) {
+			console.warn(`Warning: Failed to process ${filePath}:`, error)
+		}
+	}
+
+	return {
+		posts,
+		postsByLanguage,
+		postsBySlug,
+	}
+}
+
+/**
+ * Filter blog posts by specific criteria
+ * Useful for separating blog posts from docs
+ */
+export function filterBlogPosts(
+	posts: BlogPostMetadata[],
+	predicate: (post: BlogPostMetadata) => boolean,
+): BlogPostMetadata[] {
+	return posts.filter(predicate)
+}

package/vite-config/index.ts

@@ -0,0 +1,17 @@
+// Blog discovery
+export { discoverBlogPosts, filterBlogPosts } from './blog-discovery.ts'
+
+// Meta tag generation
+export {
+	generateHtmlWithMetaTags,
+	generateMetaTags,
+	generateMetaTagsObject,
+	type MetaTagsOptions,
+} from './meta-tags.ts'
+// SSG setup utilities (recommended for consumers)
+export { type SetupSSGOptions, setupSSG } from './setup-ssg.ts'
+// Vite plugin
+export {
+	createStaticGenPlugin,
+	type StaticGenPluginOptions,
+} from './static-gen-plugin.ts'

package/vite-config/meta-tags.ts

@@ -0,0 +1,184 @@
+import type { BlogPostMetadata } from './types.ts'
+
+export interface MetaTagsOptions {
+	/** Base URL for absolute OG image URLs */
+	baseUrl?: string
+	/** Default OG image URL if post doesn't have one */
+	defaultOgImage?: string
+	/** Site title for Twitter Card */
+	siteTitle?: string
+	/** Site name for OG tags */
+	siteName?: string
+	/** Twitter handle for Twitter Card */
+	twitterHandle?: string
+}
+
+/**
+ * Generate meta tags HTML string from blog post metadata
+ */
+export function generateMetaTags(
+	post: BlogPostMetadata,
+	options: MetaTagsOptions = {},
+): string {
+	const {
+		baseUrl = 'https://docs.staking.polkadot.cloud',
+		defaultOgImage = '/img/og-image.png',
+		siteTitle = 'Polkadot Cloud Staking',
+		siteName = 'Polkadot Cloud Staking Documentation',
+		twitterHandle = '@PolkadotCloud',
+	} = options
+
+	const postUrl = `${baseUrl}/${post.language}/docs/${post.slug}`
+	const ogImage = post.ogImage
+		? `${baseUrl}${post.ogImage.startsWith('/') ? '' : '/'}${post.ogImage}`
+		: `${baseUrl}${defaultOgImage}`
+
+	// Normalize keywords
+	let keywordsString = ''
+	if (post.keywords) {
+		if (Array.isArray(post.keywords)) {
+			keywordsString = post.keywords.join(', ')
+		} else {
+			keywordsString = post.keywords
+		}
+	}
+
+	const tags: string[] = [
+		// Basic meta tags
+		`<meta name="description" content="${escapeHtml(post.description || siteTitle)}">`,
+		`<meta name="viewport" content="width=device-width, initial-scale=1.0">`,
+
+		// Open Graph (OG) tags
+		`<meta property="og:type" content="article">`,
+		`<meta property="og:title" content="${escapeHtml(post.title)} | ${escapeHtml(siteName)}">`,
+		`<meta property="og:description" content="${escapeHtml(post.description || siteTitle)}">`,
+		`<meta property="og:url" content="${escapeHtml(postUrl)}">`,
+		`<meta property="og:image" content="${escapeHtml(ogImage)}">`,
+		`<meta property="og:site_name" content="${escapeHtml(siteName)}">`,
+
+		// Article-specific meta tags
+		`<meta property="article:published_time" content="${post.date || new Date().toISOString()}">`,
+		post.author
+			? `<meta property="article:author" content="${escapeHtml(post.author)}">`
+			: '',
+
+		// Twitter Card tags
+		`<meta name="twitter:card" content="summary_large_image">`,
+		`<meta name="twitter:site" content="${twitterHandle}">`,
+		`<meta name="twitter:title" content="${escapeHtml(post.title)} | ${escapeHtml(siteName)}">`,
+		`<meta name="twitter:description" content="${escapeHtml(post.description || siteTitle)}">`,
+		`<meta name="twitter:image" content="${escapeHtml(ogImage)}">`,
+
+		// Keywords
+		keywordsString
+			? `<meta name="keywords" content="${escapeHtml(keywordsString)}">`
+			: '',
+
+		// Canonical URL
+		`<link rel="canonical" href="${escapeHtml(postUrl)}">`,
+	]
+
+	return tags.filter(Boolean).join('\n\t')
+}
+
+/**
+ * Escape HTML special characters in attribute values
+ */
+function escapeHtml(text: string): string {
+	const map: Record<string, string> = {
+		'&': '&amp;',
+		'<': '&lt;',
+		'>': '&gt;',
+		'"': '&quot;',
+		"'": '&#039;',
+	}
+	return text.replace(/[&<>"']/g, (char) => map[char])
+}
+
+/**
+ * Generate an HTML template with injected meta tags
+ * Used for static page generation
+ */
+export function generateHtmlWithMetaTags(
+	baseHtml: string,
+	post: BlogPostMetadata,
+	options: MetaTagsOptions = {},
+): string {
+	const metaTags = generateMetaTags(post, options)
+
+	// Remove default OG and Twitter meta tags to replace them with custom ones
+	let html = baseHtml
+		// Remove default og:* meta tags (handles multiline)
+		.replace(/<meta\s+property="og:[^"]*"[^>]*>/gis, '')
+		// Remove default article:* meta tags (handles multiline)
+		.replace(/<meta\s+property="article:[^"]*"[^>]*>/gis, '')
+		// Remove default twitter:* meta tags with either 'name' or 'property' attribute (handles multiline)
+		.replace(/<meta\s+(?:name|property)="twitter:[^"]*"[^>]*>/gis, '')
+		// Remove default description tag
+		.replace(/<meta\s+name="description"[^>]*>/gis, '')
+		// Remove canonical link if present
+		.replace(/<link\s+rel="canonical"[^>]*>/gis, '')
+
+	// Clean up excess blank lines left by removed tags
+	html = html.replace(/\n\s*\n\s*\n/g, '\n\n')
+
+	// Remove orphaned section comments followed by blank lines
+	html = html.replace(
+		/\s*<!--\s*(?:Open Graph|Facebook|Twitter)[^>]*-->\s*\n/g,
+		'',
+	)
+
+	// Final cleanup: remove any remaining multiple blank lines
+	html = html.replace(/\n\s*\n\s*\n/g, '\n\n')
+
+	// Inject custom meta tags before closing </head> tag
+	return html.replace('</head>', `\t${metaTags}\n</head>`)
+}
+
+/**
+ * Generate meta tags as a JSON object for dynamic injection
+ * Useful if you want to update meta tags on client-side navigation
+ */
+export function generateMetaTagsObject(
+	post: BlogPostMetadata,
+	options: MetaTagsOptions = {},
+): Record<string, string> {
+	const {
+		baseUrl = 'https://docs.staking.polkadot.cloud',
+		defaultOgImage = '/img/og-image.png',
+		siteName = 'Polkadot Cloud Staking Documentation',
+	} = options
+
+	const postUrl = `${baseUrl}/${post.language}/docs/${post.slug}`
+	const ogImage = post.ogImage
+		? `${baseUrl}${post.ogImage.startsWith('/') ? '' : '/'}${post.ogImage}`
+		: `${baseUrl}${defaultOgImage}`
+
+	// Normalize keywords
+	let keywordsArray: string[] = []
+	if (post.keywords) {
+		if (Array.isArray(post.keywords)) {
+			keywordsArray = post.keywords
+		} else {
+			keywordsArray = post.keywords.split(',').map((k) => k.trim())
+		}
+	}
+
+	return {
+		description: post.description || siteName,
+		'og:type': 'article',
+		'og:title': `${post.title} | ${siteName}`,
+		'og:description': post.description || siteName,
+		'og:url': postUrl,
+		'og:image': ogImage,
+		'og:site_name': siteName,
+		'article:published_time': post.date || new Date().toISOString(),
+		...(post.author && { 'article:author': post.author }),
+		'twitter:card': 'summary_large_image',
+		'twitter:title': `${post.title} | ${siteName}`,
+		'twitter:description': post.description || siteName,
+		'twitter:image': ogImage,
+		...(keywordsArray.length > 0 && { keywords: keywordsArray.join(', ') }),
+		canonical: postUrl,
+	}
+}

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
+}