migrate-gitbook.ts

#!/usr/bin/env ts-node

const fs = require('fs');
const path = require('path');

interface CliOptions {
  project?: string;
  help?: boolean;
}

interface SidebarItem {
  type: 'doc' | 'category' | 'link';
  id?: string;
  label?: string;
  items?: SidebarItem[];
  href?: string;
}


class GitBookMigrator {
  private gitbookDir = './gitbook-docs';
  private docsDir = './docs';
  private staticDir = './static';

  async migrateAllProjects(specificProject?: string): Promise<void> {
    console.log('🚀 Starting GitBook to Docusaurus migration...');

    const allProjects = fs.readdirSync(this.gitbookDir, { withFileTypes: true })
      .filter(dirent => dirent.isDirectory())
      .map(dirent => dirent.name);

    let projects: string[];

    if (specificProject) {
      if (!allProjects.includes(specificProject)) {
        throw new Error(`❌ Project "${specificProject}" not found. Available projects: ${allProjects.join(', ')}`);
      }
      projects = [specificProject];
      console.log(`📂 Migrating specific project: ${specificProject}`);
    } else {
      projects = allProjects;
      console.log(`📂 Found projects: ${projects.join(', ')}`);
    }

    for (const project of projects) {
      console.log(`\n🔄 Processing project: ${project}`);
      await this.processProject(project);
    }

    console.log('\n✅ Migration completed successfully!');
  }

  private async processProject(projectName: string): Promise<void> {
    const projectPath = path.join(this.gitbookDir, projectName);
    const targetDocsPath = path.join(this.docsDir, projectName);
    const targetStaticPath = path.join(this.staticDir, projectName, 'imgs');

    // Create target directories
    this.ensureDirectoryExists(targetDocsPath);
    this.ensureDirectoryExists(targetStaticPath);

    console.log(`  📝 Converting README.md to Introduction.md`);
    await this.convertReadmeToIntroduction(projectPath, targetDocsPath);

    console.log(`  🗂️  Generating sidebars.js from SUMMARY.md`);
    await this.generateSidebarsFromSummary(projectPath, targetDocsPath);

    console.log(`  📸 Copying assets to static folder`);
    await this.copyAssets(projectPath, targetStaticPath);

    console.log(`  📄 Copying and updating documentation files`);
    await this.copyAndUpdateDocs(projectPath, targetDocsPath, projectName);

    console.log(`  ✅ Project ${projectName} migration completed`);
  }

  private async convertReadmeToIntroduction(projectPath: string, targetDocsPath: string): Promise<void> {
    const readmePath = path.join(projectPath, 'README.md');
    const introductionPath = path.join(targetDocsPath, 'Introduction.md');

    if (!fs.existsSync(readmePath)) {
      console.log(`    ⚠️  README.md not found in ${projectPath}`);
      return;
    }

    let content = fs.readFileSync(readmePath, 'utf-8');

    // Format the document using the comprehensive formatter
    content = this.formatDocFile(content, projectPath.split('/').pop()!);

    fs.writeFileSync(introductionPath, content, 'utf-8');
  }

  private async generateSidebarsFromSummary(projectPath: string, targetDocsPath: string): Promise<void> {
    const summaryPath = path.join(projectPath, 'SUMMARY.md');
    const sidebarPath = path.join(targetDocsPath, 'sidebars.js');

    if (!fs.existsSync(summaryPath)) {
      console.log(`    ⚠️  SUMMARY.md not found in ${projectPath}`);
      return;
    }

    const summaryContent = fs.readFileSync(summaryPath, 'utf-8');
    const sidebarItems = this.parseSummaryToSidebar(summaryContent);

    const sidebarConfig = `module.exports = {
  myAutogeneratedSidebar: [
    {
      type: "doc",
      id: "Introduction",
      label: "📖 Introduction",
    },
${this.generateSidebarItemsString(sidebarItems, '    ')}
  ],
};
`;

    fs.writeFileSync(sidebarPath, sidebarConfig, 'utf-8');
  }

  private parseSummaryToSidebar(summaryContent: string): SidebarItem[] {
    const lines = summaryContent.split('\n');
    const items: SidebarItem[] = [];
    let currentCategory: SidebarItem | null = null;
    const stack: SidebarItem[] = []; // Stack to track nested categories

    for (const line of lines) {
      const trimmedLine = line.trim();

      // Skip empty lines and main title header (single #)
      if (!trimmedLine || (trimmedLine.startsWith('#') && !trimmedLine.startsWith('##'))) continue;

      // Check if this is a section header (##)
      if (trimmedLine.startsWith('##')) {
        const categoryLabel = trimmedLine.replace(/^##\s*/, '').trim();
        currentCategory = {
          type: 'category',
          label: categoryLabel,
          items: []
        };
        items.push(currentCategory);
        stack.length = 0; // Clear stack for new top-level category
        continue;
      }

      // Check if this is a doc item (* [Title](path))
      const docMatch = line.match(/^(\s*)\*\s*\[([^\]]+)\]\(([^)]+)\)$/);
      if (docMatch) {
        const [, indentation, title, filePath] = docMatch;
        const indentLevel = indentation.length;

        // Skip README.md as it's converted to Introduction.md
        if (filePath === 'README.md') continue;

        const docId = this.filePathToDocId(filePath);

        // Determine if this is a nested item (indented)
        if (indentLevel > 0 && stack.length > 0) {
          // This is a nested item, add to the last doc item in stack as a category
          const parentItem = stack[stack.length - 1];

          // Convert parent to category if it's not already
          if (parentItem.type === 'doc') {
            const parentDocId = parentItem.id;
            const parentLabel = parentItem.label;

            // Convert to category and add the parent doc as the first item
            parentItem.type = 'category';
            parentItem.items = [
              {
                type: 'doc',
                id: parentDocId,
                label: parentLabel
              }
            ];
            delete parentItem.id; // Remove id when converting to category
          }

          const nestedDocItem: SidebarItem = {
            type: 'doc',
            id: docId,
            label: title
          };

          if (parentItem.items) {
            parentItem.items.push(nestedDocItem);
          }
        } else {
          // This is a top-level item
          const docItem: SidebarItem = {
            type: 'doc',
            id: docId,
            label: title
          };

          if (currentCategory && currentCategory.items) {
            currentCategory.items.push(docItem);
            stack.push(docItem); // Add to stack for potential nesting
          } else {
            items.push(docItem);
            stack.push(docItem); // Add to stack for potential nesting
          }
        }
      }
    }

    return items;
  }

  private escapeQuotesInLabel(label: string): string {
    // Escape double quotes in labels to prevent syntax errors
    return label.replace(/"/g, '\\"');
  }

  private generateSidebarItemsString(items: SidebarItem[], indent: string): string {
    return items.map(item => {
      if (item.type === 'category') {
        const nestedItems = item.items ? this.generateSidebarItemsString(item.items, indent + '  ') : '';
        const escapedLabel = this.escapeQuotesInLabel(item.label || '');
        return `${indent}{
${indent}  type: "category",
${indent}  label: "${escapedLabel}",
${indent}  items: [
${nestedItems}
${indent}  ],
${indent}},`;
      } else if (item.type === 'doc') {
        const escapedLabel = this.escapeQuotesInLabel(item.label || '');
        return `${indent}{ type: "doc", id: "${item.id}", label: "${escapedLabel}" },`;
      }
      return '';
    }).join('\n');
  }

  private async copyAssets(projectPath: string, targetStaticPath: string): Promise<void> {
    const assetsPath = path.join(projectPath, '.gitbook', 'assets');

    if (!fs.existsSync(assetsPath)) {
      console.log(`    ⚠️  Assets folder not found in ${projectPath}`);
      return;
    }

    this.copyDirectory(assetsPath, targetStaticPath);
  }

  private async copyAndUpdateDocs(projectPath: string, targetDocsPath: string, projectName: string): Promise<void> {
    const items = fs.readdirSync(projectPath, { withFileTypes: true });

    for (const item of items) {
      // Skip special GitBook files and directories
      if (['README.md', 'SUMMARY.md', '.gitbook', '.git'].includes(item.name)) {
        continue;
      }

      const sourcePath = path.join(projectPath, item.name);
      const targetPath = path.join(targetDocsPath, item.name);

      if (item.isDirectory()) {
        this.ensureDirectoryExists(targetPath);
        this.copyDocumentationDirectory(sourcePath, targetPath, projectName);
      } else if (item.name.endsWith('.md')) {
        this.copyAndUpdateMarkdownFile(sourcePath, targetPath, projectName);
      }
    }
  }

  private copyDocumentationDirectory(sourceDir: string, targetDir: string, projectName: string): void {
    const items = fs.readdirSync(sourceDir, { withFileTypes: true });

    for (const item of items) {
      const sourcePath = path.join(sourceDir, item.name);
      const targetPath = path.join(targetDir, item.name);

      if (item.isDirectory()) {
        this.ensureDirectoryExists(targetPath);
        this.copyDocumentationDirectory(sourcePath, targetPath, projectName);
      } else if (item.name.endsWith('.md')) {
        this.copyAndUpdateMarkdownFile(sourcePath, targetPath, projectName);
      }
    }
  }

  private copyAndUpdateMarkdownFile(sourcePath: string, targetPath: string, projectName: string): void {
    let content = fs.readFileSync(sourcePath, 'utf-8');

    // Format the document using the comprehensive formatter
    content = this.formatDocFile(content, projectName);

    fs.writeFileSync(targetPath, content, 'utf-8');
  }

  private removeAllFrontmatter(content: string): string {
    // Remove any frontmatter (GitBook or existing Docusaurus)
    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n\n?/);
    if (frontmatterMatch) {
      return content.substring(frontmatterMatch[0].length);
    }
    return content;
  }

  private convertGitBookTables(content: string): string {
    // Convert GitBook table syntax to CardGrid components
    // Look for the specific comment pattern followed by table HTML
    const tablePattern = /<!-- Table converted from GitBook format -->\s*\n<table[\s\S]*?<\/table>/gi;

    content = content.replace(tablePattern, (match) => {
      return this.parseGitBookTableToCardGrid(match);
    });

    // Also handle tables without the comment (in case some are missed)
    const directTablePattern = /<table[^>]*data-view="cards"[\s\S]*?<\/table>/gi;
    content = content.replace(directTablePattern, (match) => {
      // Only convert if it's not already processed (doesn't have the comment)
      if (!match.includes('<!-- Table converted from GitBook format -->')) {
        return this.parseGitBookTableToCardGrid(match);
      }
      return match;
    });

    return content;
  }

  private parseGitBookTableToCardGrid(tableHtml: string): string {
    // Parse GitBook table and convert to CardGrid component
    // First, clean the input by removing the comment if present
    const cleanTableHtml = tableHtml.replace(/<!-- Table converted from GitBook format -->\s*\n?/gi, '');

    const tableType = this.detectTableType(cleanTableHtml);

    // Extract table rows
    const rowMatches = cleanTableHtml.match(/<tr[\s\S]*?<\/tr>/gi);
    if (!rowMatches || rowMatches.length < 2) {
      console.log(`    ⚠️  Could not parse table rows, returning original`);
      return tableHtml; // Return original if can't parse
    }

    // Skip header row, process data rows
    const dataRows = rowMatches.slice(1);
    const cards: string[] = [];

    for (const row of dataRows) {
      const card = this.parseTableRowToCard(row, tableType);
      if (card) {
        cards.push(card);
      }
    }

    if (cards.length === 0) {
      console.log(`    ⚠️  No cards extracted from table, returning original`);
      return tableHtml; // Return original if no cards extracted
    }

    const gridType = this.getGridTypeFromTableType(tableType);

    console.log(`    ✅ Converted table to CardGrid with ${cards.length} cards (type: ${gridType})`);

    return `<CardGrid type="${gridType}">
${cards.join('\n')}
</CardGrid>`;
  }

  private detectTableType(tableHtml: string): 'selfService' | 'default' {
    // All GitBook tables will be processed as self-service cards
    if (tableHtml.includes('data-view="cards"') || tableHtml.includes('<table')) {
      return 'selfService';
    }

    return 'default';
  }

  private getGridTypeFromTableType(tableType: string): string {
    switch (tableType) {
      case 'selfService': return 'selfService';
      default: return 'default';
    }
  }

  private parseTableRowToCard(rowHtml: string, tableType: string): string | null {
    // Extract cell contents
    const cellMatches = rowHtml.match(/<td[\s\S]*?<\/td>/gi);
    if (!cellMatches) return null;

    let title = '';
    let link = '';

    // Parse cells to extract content
    for (const cell of cellMatches) {
      const cellContent = cell.replace(/<\/?td[^>]*>/gi, '').trim();

      if (!cellContent || cellContent === '') continue;

      // Extract links
      const linkMatch = cellContent.match(/<a[^>]+href="([^"]+)"[^>]*>/);
      if (linkMatch) {
        link = linkMatch[1];
      }

      // Extract strong text (titles)
      const strongMatch = cellContent.match(/<strong[^>]*>(.*?)<\/strong>/);
      if (strongMatch) {
        title = strongMatch[1].trim();
      }
    }

    if (!title) return null;

    // All GitBook tables use the same self-service card format
    return this.generateSelfServiceCard(title, link);
  }

  private generateSelfServiceCard(title: string, link: string): string {
    const linkProp = link ? ` link="${link}"` : '';

    return `  <Card
    title="${this.escapeQuotesInLabel(title)}"${linkProp}
  />`;
  }

  private convertGitBookHints(content: string): string {
    // Convert GitBook hint blocks to custom Hint component
    // Pattern: {% hint style="info" %} ... {% endhint %}
    const hintPattern = /{% hint style="(info|warning|danger|success)" %}\n([\s\S]*?)\n{% endhint %}/g;

    return content.replace(hintPattern, (match, style, hintContent) => {
      // Clean up the hint content by trimming whitespace
      const cleanContent = hintContent.trim();

      // Convert to JSX Hint component with import
      return `<Hint style="${style}">
${cleanContent}
</Hint>`;
    });
  }

  private addComponentImports(content: string): string {
    const imports: string[] = [];

    // Check if the content contains any Hint components
    if (content.includes('<Hint')) {
      imports.push("import Hint from '@site/src/components/Hint';");
    }

    // Check if the content contains any CardGrid components
    if (content.includes('<CardGrid') || content.includes('<Card')) {
      imports.push("import CardGrid, { Card } from '@site/src/components/CardGrid';");
    }

    if (imports.length > 0) {
      return imports.join('\n') + '\n\n' + content;
    }

    return content;
  }

  private fixUnclosedImgTags(content: string): string {
    // Fix unclosed img tags by converting <img ...> to <img ... />
    // This handles both single-line and multi-line img tags
    return content.replace(/<img([^>]*?)(?<!\/)>/g, '<img$1 />');
  }

  private convertGitBookEmbeds(content: string): string {
    // Convert GitBook embed blocks to iframe elements
    // Pattern: {% embed url="https://www.youtube.com/watch?v=VIDEO_ID" %}
    const embedPattern = /{% embed url="([^"]+)" %}/g;

    return content.replace(embedPattern, (match, url) => {
      // Check if it's a YouTube URL and convert to embed format
      const youtubeMatch = url.match(/(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]+)/);

      if (youtubeMatch) {
        const videoId = youtubeMatch[1];
        const embedUrl = `https://www.youtube.com/embed/${videoId}`;

        return `<iframe height="400" width="100%" src="${embedUrl}" title="Video" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>`;
      }

      // For other URLs, create a generic iframe
      return `<iframe height="400" width="100%" src="${url}" title="Embedded Content" frameBorder="0" allowFullScreen></iframe>`;
    });
  }

  private disableSingleDollarLatex(content: string): string {
    // Escape single dollar signs to prevent LaTeX rendering
    // This is specific to GitBook projects that don't support single dollar LaTeX syntax
    // Pattern: $ (single dollar not followed by another dollar)
    // We need to be careful not to escape double dollars ($$)

    return content.replace(/(?<!\$)\$(?!\$)/g, '\\$');
  }

  private removeMarkdownExtensions(content: string): string {
    // Remove .md extensions from all internal links to follow Docusaurus link format
    // Pattern: href="something.md" or [text](something.md) or <a href="something.md">

    // Handle markdown links: [text](file.md) -> [text](file)
    content = content.replace(/\[([^\]]*)\]\(([^)]+)\.md(#[^)]*)?(\)|#[^)]*\))/g, (match, text, link, anchor, closeParen) => {
      const finalAnchor = anchor || '';
      return `[${text}](${link}${finalAnchor})`;
    });

    // Handle HTML href attributes: href="file.md" -> href="file"
    content = content.replace(/href="([^"]+)\.md(#[^"]*)?"/g, (match, link, anchor) => {
      const finalAnchor = anchor || '';
      return `href="${link}${finalAnchor}"`;
    });

    // Handle card links: link="file.md#anchor" -> link="file#anchor"
    content = content.replace(/link="([^"]+)\.md(#[^"]*)?"/g, (match, link, anchor) => {
      const finalAnchor = anchor || '';
      return `link="${link}${finalAnchor}"`;
    });

    return content;
  }

  private stripInvalidEntities(content: string): string {
    // Strip down all "&#xNAN;" invalid HTML entities from the content
    return content.replace(/&#xNAN;/g, '');
  }

  private formatDocFile(content: string, projectName: string): string {
    // Remove all existing frontmatter
    content = this.removeAllFrontmatter(content);

    // Convert GitBook table syntax
    content = this.convertGitBookTables(content);

    // Convert GitBook hints to custom Hint components
    content = this.convertGitBookHints(content);

    // Convert GitBook embeds to iframe elements
    content = this.convertGitBookEmbeds(content);

    // Disable single dollar LaTeX syntax for GitBook projects
    content = this.disableSingleDollarLatex(content);

    // Remove .md extensions from internal links
    content = this.removeMarkdownExtensions(content);

    // Strip invalid HTML entities
    content = this.stripInvalidEntities(content);

    // Fix unclosed img tags
    content = this.fixUnclosedImgTags(content);

    // Update image paths
    content = this.updateImagePathsInContent(content, projectName);

    // Add component imports if needed
    content = this.addComponentImports(content);

    return content;
  }

  private updateImagePathsInContent(content: string, projectName: string): string {
    // Replace GitBook image paths with Docusaurus static paths
    // Pattern: ../.gitbook/assets/filename.ext -> /projectName/imgs/filename.ext
    return content.replace(/\.\.\/\.gitbook\/assets\//g, `/${projectName}/imgs/`);
  }

  private filePathToDocId(filePath: string): string {
    // Convert file path to Docusaurus doc ID
    // Remove .md extension and replace path separators with slashes
    return filePath.replace(/\.md$/, '').replace(/\\/g, '/');
  }

  private generateTitleFromFileName(fileName: string): string {
    // Convert filename to a readable title
    return fileName
      .replace(/-/g, ' ')
      .replace(/\b\w/g, l => l.toUpperCase());
  }

  private ensureDirectoryExists(dirPath: string): void {
    if (!fs.existsSync(dirPath)) {
      fs.mkdirSync(dirPath, { recursive: true });
    }
  }

  private copyDirectory(sourceDir: string, targetDir: string): void {
    this.ensureDirectoryExists(targetDir);

    const items = fs.readdirSync(sourceDir, { withFileTypes: true });

    for (const item of items) {
      const sourcePath = path.join(sourceDir, item.name);
      const targetPath = path.join(targetDir, item.name);

      if (item.isDirectory()) {
        this.copyDirectory(sourcePath, targetPath);
      } else {
        fs.copyFileSync(sourcePath, targetPath);
      }
    }
  }
}

// Command line argument parsing
function parseArgs(args: string[]): CliOptions {
  const options: CliOptions = {};

  for (let i = 0; i < args.length; i++) {
    const arg = args[i];

    if (arg === '--help' || arg === '-h') {
      options.help = true;
    } else if (arg === '--project' || arg === '-p') {
      if (i + 1 >= args.length) {
        throw new Error('❌ --project/-p option requires a project name');
      }
      options.project = args[i + 1];
      i++; // Skip the next argument as it's the project name
    }
  }

  return options;
}

function showHelp(): void {
  console.log(`
🚀 GitBook to Docusaurus Migration Tool

Usage:
  yarn migrate-gitbook [options]

Options:
  -p, --project <name>    Migrate only the specified project
  -h, --help             Show this help message

Examples:
  yarn migrate-gitbook                    # Migrate all projects
  yarn migrate-gitbook -p boros-academy   # Migrate only boros-academy
  yarn migrate-gitbook --project pendle-academy  # Migrate only pendle-academy

Available projects will be listed if no specific project is provided.
  `);
}

// Main execution
async function main(): Promise<void> {
  const migrator = new GitBookMigrator();

  try {
    // Parse command line arguments (skip 'node' and script name)
    const args = process.argv.slice(2);
    const options = parseArgs(args);

    if (options.help) {
      showHelp();
      return;
    }

    await migrator.migrateAllProjects(options.project);
  } catch (error) {
    if (error instanceof Error) {
      console.error(error.message);
    } else {
      console.error('❌ Migration failed:', error);
    }
    process.exit(1);
  }
}

// Run the migration if this file is executed directly
if (require.main === module) {
  main();
}

module.exports = { GitBookMigrator };