docs-i18n 0.6.3 → 0.7.0

package/template/app/utils/markdown/filterFrameworkContent.ts

@@ -0,0 +1,233 @@
+/**
+ * Filters framework-specific content blocks from raw markdown.
+ *
+ * Handles two types of blocks:
+ *
+ * 1. Framework blocks:
+ *   <!-- ::start:framework -->
+ *   # React
+ *   React-specific content...
+ *   # Vue
+ *   Vue-specific content...
+ *   <!-- ::end:framework -->
+ *
+ * 2. Package manager tabs (variant="package-manager"):
+ *   <!-- ::start:tabs variant="package-manager" mode="local-install" -->
+ *   react: create-tsrouter-app@latest my-app
+ *   solid: create-tsrouter-app@latest my-app --framework solid
+ *   <!-- ::end:tabs -->
+ */
+
+import {
+  getInstallCommand,
+  type PackageManager,
+  type InstallMode,
+} from './installCommand'
+
+type FilterOptions = {
+  framework?: string
+  packageManager?: PackageManager
+  /** Whether to keep the surrounding comment markers when filtering. Defaults to false. */
+  keepMarkers?: boolean
+}
+
+/**
+ * Filters framework-specific content and package-manager tabs from raw markdown.
+ * If no framework is specified, returns markdown unchanged.
+ */
+export function filterFrameworkContent(
+  markdown: string,
+  options: FilterOptions,
+): string {
+  const { framework, packageManager, keepMarkers = false } = options
+
+  if (!framework) {
+    return markdown
+  }
+
+  const normalizedFramework = framework.toLowerCase()
+
+  // First pass: filter framework blocks
+  let result = filterFrameworkBlocks(markdown, normalizedFramework, keepMarkers)
+
+  // Second pass: filter package-manager tabs
+  result = filterPackageManagerTabs(
+    result,
+    normalizedFramework,
+    packageManager,
+    keepMarkers,
+  )
+
+  return result
+}
+
+/**
+ * Filters <!-- ::start:framework --> blocks.
+ */
+function filterFrameworkBlocks(
+  markdown: string,
+  framework: string,
+  keepMarkers: boolean,
+): string {
+  const blockRegex =
+    /(<!--\s*::start:framework\s*-->)([\s\S]*?)(<!--\s*::end:framework\s*-->)/gi
+
+  return markdown.replace(
+    blockRegex,
+    (
+      _match,
+      startComment: string,
+      blockContent: string,
+      endComment: string,
+    ) => {
+      const sections = splitByFrameworkHeadings(blockContent)
+      const frameworkSection = sections.find((s) => s.framework === framework)
+
+      if (!frameworkSection) {
+        return ''
+      }
+
+      const content = frameworkSection.content.trim()
+      if (keepMarkers) {
+        return `${startComment}\n${content}\n${endComment}`
+      }
+      return content
+    },
+  )
+}
+
+/**
+ * Filters <!-- ::start:tabs variant="package-manager" --> blocks.
+ * If framework matches and packageManager is provided, outputs the command.
+ * Otherwise returns block as-is.
+ */
+function filterPackageManagerTabs(
+  markdown: string,
+  framework: string,
+  packageManager: PackageManager | undefined,
+  keepMarkers: boolean,
+): string {
+  // Match tabs blocks with attributes
+  const blockRegex =
+    /(<!--\s*::start:tabs\s+([^>]*?)-->)([\s\S]*?)(<!--\s*::end:tabs\s*-->)/gi
+
+  return markdown.replace(
+    blockRegex,
+    (
+      fullMatch,
+      startComment: string,
+      attrs: string,
+      blockContent: string,
+      endComment: string,
+    ) => {
+      // Parse attributes to check variant
+      const variant = parseAttribute(attrs, 'variant')
+      if (variant !== 'package-manager' && variant !== 'package-managers') {
+        return fullMatch
+      }
+
+      // Parse framework lines
+      const frameworkPackages = parseFrameworkLines(blockContent)
+      const packages = frameworkPackages[framework]
+
+      // If no match for framework, return as-is
+      if (!packages || packages.length === 0) {
+        return fullMatch
+      }
+
+      // If no package manager specified, return as-is
+      if (!packageManager) {
+        return fullMatch
+      }
+
+      // Generate command based on mode
+      const mode = (parseAttribute(attrs, 'mode') as InstallMode) || 'install'
+      const commands = getInstallCommand(packageManager, packages, mode)
+      const commandText = `\`\`\`sh\n${commands.join('\n')}\n\`\`\``
+
+      // Return with or without comment markers based on keepMarkers option
+      if (keepMarkers) {
+        return `${startComment}\n${commandText}\n${endComment}`
+      }
+      return commandText
+    },
+  )
+}
+
+/**
+ * Parse a single attribute from an attribute string.
+ * e.g., parseAttribute('variant="package-manager" mode="install"', 'variant') => 'package-manager'
+ */
+function parseAttribute(attrs: string, name: string): string | undefined {
+  const regex = new RegExp(`${name}=["']([^"']+)["']`, 'i')
+  const match = attrs.match(regex)
+  return match?.[1]
+}
+
+/**
+ * Parse framework lines like "react: @tanstack/react-query" from block content.
+ * Returns { framework: [[packages]] } structure.
+ */
+function parseFrameworkLines(content: string): Record<string, string[][]> {
+  const result: Record<string, string[][]> = {}
+  const lines = content.split('\n')
+
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed) continue
+
+    const colonIndex = trimmed.indexOf(':')
+    if (colonIndex === -1) continue
+
+    const framework = trimmed.slice(0, colonIndex).trim().toLowerCase()
+    const packagesStr = trimmed.slice(colonIndex + 1).trim()
+    const packages = packagesStr.split(/\s+/).filter(Boolean)
+
+    if (!framework || packages.length === 0) continue
+
+    if (result[framework]) {
+      result[framework].push(packages)
+    } else {
+      result[framework] = [packages]
+    }
+  }
+
+  return result
+}
+
+type FrameworkSection = {
+  framework: string
+  content: string
+}
+
+/**
+ * Splits block content by H1 framework headers.
+ */
+function splitByFrameworkHeadings(blockContent: string): FrameworkSection[] {
+  const sections: FrameworkSection[] = []
+  const headerRegex = /^#\s+(\w+)\s*$/gm
+  let lastIndex = 0
+  let lastFramework: string | null = null
+  let match: RegExpExecArray | null
+
+  while ((match = headerRegex.exec(blockContent)) !== null) {
+    if (lastFramework !== null) {
+      sections.push({
+        framework: lastFramework,
+        content: blockContent.slice(lastIndex, match.index),
+      })
+    }
+
+    lastFramework = match[1].toLowerCase()
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastFramework !== null) {
+    sections.push({
+      framework: lastFramework,
+      content: blockContent.slice(lastIndex),
+    })
+  }
+
+  return sections
+}

package/template/app/utils/markdown/index.ts

@@ -0,0 +1,2 @@
+export { renderMarkdown } from './processor'
+export type { MarkdownHeading, MarkdownRenderResult } from './processor'

package/template/app/utils/markdown/installCommand.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared types and utility for generating package manager install commands.
+ * Used by both server-side markdown filtering and client-side PackageManagerTabs.
+ */
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
+
+export const PACKAGE_MANAGERS: PackageManager[] = ['npm', 'pnpm', 'yarn', 'bun']
+
+export type InstallMode =
+  | 'install'
+  | 'dev-install'
+  | 'local-install'
+  | 'create'
+  | 'custom'
+
+/**
+ * Get package manager from query parameter, defaulting to 'npm' if not specified or invalid.
+ */
+export function getPackageManager(
+  pm: string | null | undefined,
+): PackageManager {
+  if (pm && PACKAGE_MANAGERS.includes(pm as PackageManager)) {
+    return pm as PackageManager
+  }
+  return 'npm' // default
+}
+
+/**
+ * Generate install command(s) for a package manager.
+ * Each group of packages becomes one command line.
+ */
+export function getInstallCommand(
+  packageManager: PackageManager,
+  packageGroups: string[][],
+  mode: InstallMode,
+): string[] {
+  const commands: string[] = []
+
+  if (mode === 'custom') {
+    for (const packages of packageGroups) {
+      const pkgStr = packages.join(' ')
+      switch (packageManager) {
+        case 'npm':
+          commands.push(`npm ${pkgStr}`)
+          break
+        case 'pnpm':
+          commands.push(`pnpm ${pkgStr}`)
+          break
+        case 'yarn':
+          commands.push(`yarn ${pkgStr}`)
+          break
+        case 'bun':
+          commands.push(`bun ${pkgStr}`)
+          break
+      }
+    }
+    return commands
+  }
+
+  if (mode === 'create') {
+    for (const packages of packageGroups) {
+      const pkgStr = packages.join(' ')
+      switch (packageManager) {
+        case 'npm':
+          commands.push(`npm create ${pkgStr}`)
+          break
+        case 'pnpm':
+          commands.push(`pnpm create ${pkgStr}`)
+          break
+        case 'yarn':
+          commands.push(`yarn create ${pkgStr}`)
+          break
+        case 'bun':
+          commands.push(`bun create ${pkgStr}`)
+          break
+      }
+    }
+    return commands
+  }
+
+  if (mode === 'local-install') {
+    for (const packages of packageGroups) {
+      const pkgStr = packages.join(' ')
+      switch (packageManager) {
+        case 'npm':
+          commands.push(`npx ${pkgStr}`)
+          break
+        case 'pnpm':
+          commands.push(`pnpx ${pkgStr}`)
+          break
+        case 'yarn':
+          commands.push(`yarn dlx ${pkgStr}`)
+          break
+        case 'bun':
+          commands.push(`bunx ${pkgStr}`)
+          break
+      }
+    }
+    return commands
+  }
+
+  if (mode === 'dev-install') {
+    for (const packages of packageGroups) {
+      const pkgStr = packages.join(' ')
+      switch (packageManager) {
+        case 'npm':
+          commands.push(`npm i -D ${pkgStr}`)
+          break
+        case 'pnpm':
+          commands.push(`pnpm add -D ${pkgStr}`)
+          break
+        case 'yarn':
+          commands.push(`yarn add -D ${pkgStr}`)
+          break
+        case 'bun':
+          commands.push(`bun add -d ${pkgStr}`)
+          break
+      }
+    }
+    return commands
+  }
+
+  // install mode (default)
+  for (const packages of packageGroups) {
+    const pkgStr = packages.join(' ')
+    switch (packageManager) {
+      case 'npm':
+        commands.push(`npm i ${pkgStr}`)
+        break
+      case 'pnpm':
+        commands.push(`pnpm add ${pkgStr}`)
+        break
+      case 'yarn':
+        commands.push(`yarn add ${pkgStr}`)
+        break
+      case 'bun':
+        commands.push(`bun add ${pkgStr}`)
+        break
+    }
+  }
+  return commands
+}

package/template/app/utils/markdown/plugins/collectHeadings.ts

@@ -0,0 +1,104 @@
+import { visit } from 'unist-util-visit'
+import { toString } from 'hast-util-to-string'
+
+import { isHeading } from './helpers'
+
+export type MarkdownHeading = {
+  id: string
+  text: string
+  level: number
+  framework?: string
+}
+
+type HastElement = {
+  type: string
+  tagName: string
+  properties?: Record<string, unknown>
+  children?: unknown[]
+}
+
+type HastRoot = {
+  type: 'root'
+  children: unknown[]
+}
+
+type VFileData = {
+  data: Record<string, unknown>
+}
+
+const isTabsAncestor = (ancestor: HastElement) => {
+  if (ancestor.type !== 'element') {
+    return false
+  }
+
+  if (ancestor.tagName !== 'md-comment-component') {
+    return false
+  }
+
+  const component = ancestor.properties?.['data-component']
+  return typeof component === 'string' && component.toLowerCase() === 'tabs'
+}
+
+const isFrameworkPanelAncestor = (ancestor: HastElement) => {
+  if (ancestor.type !== 'element') {
+    return false
+  }
+
+  return ancestor.tagName === 'md-framework-panel'
+}
+
+export function rehypeCollectHeadings(initialHeadings?: MarkdownHeading[]) {
+  const headings = initialHeadings ?? []
+
+  return function collectHeadings(tree: HastRoot, file?: VFileData) {
+    visit(tree as any, 'element', (node: HastElement, _index, ancestors) => {
+      if (!isHeading(node)) {
+        return
+      }
+
+      if (Array.isArray(ancestors)) {
+        const insideTabs = ancestors.some((ancestor) =>
+          isTabsAncestor(ancestor as HastElement),
+        )
+        if (insideTabs) {
+          return
+        }
+      }
+
+      const id =
+        typeof node.properties?.id === 'string' ? node.properties.id : ''
+      if (!id) {
+        return
+      }
+
+      let currentFramework: string | undefined
+
+      const headingDataFramework = node.properties?.['data-framework']
+      if (typeof headingDataFramework === 'string') {
+        currentFramework = headingDataFramework
+      } else if (Array.isArray(ancestors)) {
+        const frameworkPanel = ancestors.find((ancestor) =>
+          isFrameworkPanelAncestor(ancestor as HastElement),
+        ) as HastElement | undefined
+
+        if (frameworkPanel) {
+          const dataFramework = frameworkPanel.properties?.['data-framework']
+          if (typeof dataFramework === 'string') {
+            currentFramework = dataFramework
+          }
+        }
+      }
+
+      headings.push({
+        id,
+        level: Number(node.tagName.substring(1)),
+        text: toString(node as any).trim(),
+        framework: currentFramework,
+      })
+    })
+
+    if (file) {
+      file.data.headings = headings
+    }
+  }
+}

package/template/app/utils/markdown/plugins/extractCodeMeta.ts

@@ -0,0 +1,57 @@
+import type { Root } from 'hast'
+import { visit } from 'unist-util-visit'
+
+export function extractCodeMeta() {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: any) => {
+      if (node && node.tagName === 'pre') {
+        const codeChild = Array.isArray(node.children)
+          ? node.children[0]
+          : undefined
+
+        const metaString =
+          (codeChild &&
+            ((codeChild.data && codeChild.data.meta) ||
+              (codeChild.properties && codeChild.properties.metastring))) ||
+          undefined
+
+        let filename: string | undefined = undefined
+        let framework: string | undefined = undefined
+
+        if (metaString && typeof metaString === 'string') {
+          const marker = 'title="'
+          const idx = metaString.indexOf(marker)
+
+          if (idx !== -1) {
+            const rest = metaString.slice(idx + marker.length)
+            const end = rest.indexOf('"')
+
+            if (end !== -1) {
+              filename = rest.slice(0, end)
+            }
+          }
+
+          // Extract framework attribute
+          const frameworkMarker = 'framework="'
+          const frameworkIdx = metaString.indexOf(frameworkMarker)
+
+          if (frameworkIdx !== -1) {
+            const rest = metaString.slice(frameworkIdx + frameworkMarker.length)
+            const end = rest.indexOf('"')
+
+            if (end !== -1) {
+              framework = rest.slice(0, end).toLowerCase()
+            }
+          }
+        }
+
+        node.properties = {
+          ...(node.properties || {}),
+          'data-filename': filename,
+          ...(filename ? { 'data-code-title': filename } : {}),
+          ...(framework ? { 'data-framework': framework } : {}),
+        }
+      }
+    })
+  }
+}

package/template/app/utils/markdown/plugins/helpers.ts

@@ -0,0 +1,33 @@
+import { isElement } from 'hast-util-is-element'
+
+type HastElement = {
+  type: string
+  tagName: string
+  properties?: Record<string, unknown>
+  children?: unknown[]
+}
+
+export const normalizeComponentName = (name: string) => name.toLowerCase()
+
+export const slugify = (value: string, fallback: string) => {
+  if (!value) {
+    return fallback
+  }
+
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .replace(/-+/g, '-')
+      .replace(/^-|-$/g, '')
+      .slice(0, 64) || fallback
+  )
+}
+
+export const isHeading = (node: unknown): node is HastElement =>
+  isElement(node as any) && /^h[1-6]$/.test((node as HastElement).tagName)
+
+export const headingLevel = (node: HastElement) =>
+  Number(node.tagName.substring(1))

package/template/app/utils/markdown/plugins/index.ts

@@ -0,0 +1,8 @@
+export { rehypeParseCommentComponents } from './parseCommentComponents'
+export { rehypeTransformCommentComponents } from './transformCommentComponents'
+export {
+  rehypeTransformFrameworkComponents,
+  transformFrameworkComponent,
+} from './transformFrameworkComponent'
+export { transformTabsComponent } from './transformTabsComponent'
+export { type MarkdownHeading, rehypeCollectHeadings } from './collectHeadings'

package/template/app/utils/markdown/plugins/parseCommentComponents.ts

@@ -0,0 +1,103 @@
+import { unified } from 'unified'
+import rehypeParse from 'rehype-parse'
+import { SKIP, visit } from 'unist-util-visit'
+
+const COMPONENT_PREFIX = '::'
+const START_PREFIX = '::start:'
+const END_PREFIX = '::end:'
+
+const componentParser = unified().use(rehypeParse, { fragment: true })
+
+const normalizeComponentName = (name: string) => name.toLowerCase()
+
+function parseDescriptor(descriptor: string) {
+  const tree = componentParser.parse(`<${descriptor} />`)
+  const node = tree.children[0]
+  if (!node || node.type !== 'element') {
+    return null
+  }
+
+  const component = node.tagName
+  const attributes: Record<string, string> = {}
+  const properties = node.properties ?? {}
+  for (const [key, value] of Object.entries(properties)) {
+    if (Array.isArray(value)) {
+      attributes[key] = value.join(' ')
+    } else if (value != null) {
+      attributes[key] = String(value)
+    }
+  }
+
+  return { component, attributes }
+}
+
+const isCommentNode = (value: unknown) =>
+  Boolean(
+    value &&
+    typeof value === 'object' &&
+    'type' in value &&
+    value.type === 'comment',
+  )
+
+export const rehypeParseCommentComponents = () => {
+  return (tree: any) => {
+    visit(tree, 'comment', (node, index, parent) => {
+      if (!isCommentNode(node) || parent == null || typeof index !== 'number') {
+        return
+      }
+
+      const trimmed = node.value.trim()
+      if (!trimmed.startsWith(COMPONENT_PREFIX)) {
+        return
+      }
+
+      const isBlock = trimmed.startsWith(START_PREFIX)
+      const descriptor = isBlock
+        ? trimmed.slice(START_PREFIX.length)
+        : trimmed.slice(COMPONENT_PREFIX.length)
+
+      const parsed = parseDescriptor(descriptor)
+      if (!parsed) {
+        return
+      }
+
+      const componentName = parsed.component
+      const element = {
+        type: 'element',
+        tagName: 'md-comment-component',
+        properties: {
+          'data-component': componentName,
+          'data-attributes': JSON.stringify(parsed.attributes ?? {}),
+        },
+        children: [],
+      }
+
+      if (!isBlock) {
+        parent.children.splice(index, 1, element)
+        return [SKIP, index]
+      }
+
+      let endIndex = -1
+      for (let cursor = index + 1; cursor < parent.children.length; cursor++) {
+        const candidate = parent.children[cursor]
+        if (
+          isCommentNode(candidate) &&
+          candidate.value.trim().toLowerCase() ===
+            `${END_PREFIX}${normalizeComponentName(componentName)}`
+        ) {
+          endIndex = cursor
+          break
+        }
+      }
+
+      if (endIndex === -1) {
+        parent.children.splice(index, 1, element)
+        return [SKIP, index]
+      }
+
+      element.children = parent.children.slice(index + 1, endIndex)
+      parent.children.splice(index, endIndex - index + 1, element)
+      return [SKIP, index]
+    })
+  }
+}

package/template/app/utils/markdown/plugins/transformCommentComponents.ts

@@ -0,0 +1,23 @@
+import { visit } from 'unist-util-visit'
+
+import { normalizeComponentName } from './helpers'
+import { transformTabsComponent } from './transformTabsComponent'
+
+export const rehypeTransformCommentComponents = () => {
+  return (tree: any) => {
+    visit(tree, 'element', (node) => {
+      if (node.tagName !== 'md-comment-component') {
+        return
+      }
+
+      const component = String(node.properties?.['data-component'] ?? '')
+      switch (normalizeComponentName(component)) {
+        case 'tabs':
+          transformTabsComponent(node)
+          break
+        default:
+          break
+      }
+    })
+  }
+}