portosaurus 0.14.0

package/src/utils/generateRobotsTxt.js

@@ -0,0 +1,97 @@
+const path = require('path');
+const fs = require('fs');
+
+
+function formatRules(rules) {
+  if (!Array.isArray(rules) || !rules.length) return '';
+  
+  let content = '';
+  
+  rules.forEach(rule => {
+
+    // Default userAgent to '*' if not specified
+    const userAgent = rule.userAgent || '*';
+    
+    content += `User-agent: ${userAgent}\n`;
+    
+    // Check if root path is explicitly disallowed
+    const disallowsRoot = Array.isArray(rule.disallow) && 
+      rule.disallow.some(path => path === '/' || path === '/*');
+    
+    // Process allow directives
+    if (Array.isArray(rule.allow) && rule.allow.length > 0) {
+
+      // Use explicitly defined allow rules
+      for (const allowPath of rule.allow) {
+        content += `Allow: ${allowPath}\n`;
+      }
+
+    } else if (!disallowsRoot) {
+      content += `Allow: /\n`;
+    }
+    
+    // Process disallow directives
+    if (Array.isArray(rule.disallow)) {
+      for (const disallowPath of rule.disallow) {
+        content += `Disallow: ${disallowPath}\n`;
+      }
+    }
+    
+    content += '\n';
+  });
+  
+  return content;
+}
+
+
+module.exports = function() {
+  return {
+    name: 'generate-robots-txt',
+    
+    async postBuild({ outDir, siteConfig }) {
+      const robotsConfig = siteConfig.customFields?.robotsTxt;
+      
+      // Early return if robots.txt is disabled
+      if (!robotsConfig || robotsConfig.enable === false) {
+        console.log('ℹ️ robots.txt generation is disabled in config');
+        return;
+      }
+      
+      try {
+        const robotsTxtPath = path.join(outDir, 'robots.txt');
+        let content = '';
+        
+        // Process the rules structure
+        if (robotsConfig.rules) {
+          content += formatRules(robotsConfig.rules);
+        }
+        
+        // Always include sitemap reference
+        content += `Sitemap: ${siteConfig.url}/sitemap.xml\n`;
+        
+        if (Array.isArray(robotsConfig.customLines) && robotsConfig.customLines.length) {
+
+          const filteredCustomLines = robotsConfig.customLines.filter(
+            line => !line.trim().toLowerCase().startsWith('sitemap:')
+          );
+          
+          if (filteredCustomLines.length > 0) {
+            content += filteredCustomLines.join('\n') + '\n';
+          }
+        }
+        
+        // Only write file if we have content
+        if (content) {
+          fs.writeFileSync(robotsTxtPath, content, 'utf8');
+          console.log('✅ robots.txt generated successfully');
+
+        } else {
+          console.warn('⚠️ Warning: No robots.txt rules defined in config');
+        }
+
+      } catch (error) {
+        console.error('❌ Error generating robots.txt:', error);
+      }
+    }
+  };
+};

package/src/utils/iconExtractor.js

@@ -0,0 +1,159 @@
+const fs = require('fs');
+const path = require('path');
+const React = require('react');
+const ReactDOMServer = require('react-dom/server');
+const { iconMap } = require('../config/iconMappings');
+
+/// AI Generated
+
+/**
+ * Dynamically requires a React Icon
+ * @param {string} iconPath - Path in format "package/IconName" (e.g., "ai/AiFillAlert")
+ * @returns {Object|null} The icon component or null if not found
+ */
+function requireDynamicIcon(iconPath) {
+  try {
+    const [packageName, iconName] = iconPath.split('/');
+    
+    if (packageName && iconName) {
+      const iconPackage = require(`react-icons/${packageName}`);
+      return iconPackage[iconName];
+    }
+    return null;
+  } catch (error) {
+    console.error(`Failed to import icon ${iconPath}:`, error.message);
+    return null;
+  }
+}
+
+/**
+ * Cleans SVG string to create a properly formatted standalone SVG file
+ * @param {string} svgString - The SVG string from ReactDOMServer
+ * @param {string} color - The color to apply to the SVG
+ * @returns {string} Clean SVG content
+ */
+function cleanSvgString(svgString, color) {
+
+  // Remove React-specific attributes and add proper XML declaration
+  let cleanedSvg = svgString
+    .replace(/<!--.*?-->/g, '') // Remove comments
+    .replace(/stroke="currentColor"/g, `stroke="${color}"`)
+    .replace(/fill="currentColor"/g, `fill="${color}"`);
+
+  // Add XML declaration if not present
+  if (!cleanedSvg.includes('<?xml')) {
+    cleanedSvg = `<?xml version="1.0" encoding="UTF-8" standalone="no"?>\n${cleanedSvg}`;
+  }
+
+  // Add viewBox if not present
+  if (!cleanedSvg.includes('viewBox')) {
+    cleanedSvg = cleanedSvg.replace('<svg', '<svg viewBox="0 0 24 24"');
+  }
+
+  return cleanedSvg;
+}
+
+/**
+ * Extracts SVG content from a React Icon component and saves it to a file
+ * 
+ * @param {React.ComponentType|string} icon - Icon component, name from iconMap, or path like "ai/AiFillAlert"
+ * @param {string} outputPath - Path to save the SVG file, defaults to static/img/svg if not provided
+ * @param {object} options - Additional options
+ * @param {string} options.color - Icon color (default: 'white')
+ * @param {number} options.size - Icon size (default: 24)
+ * @param {string} options.filename - Override filename (default: icon-<name>.svg)
+ * @param {string} options.iconName - Specify icon name instead of using component name
+ * @returns {string} The path to the saved SVG file
+ */
+function extractSvg(icon, outputPath = null, options = {}) {
+
+  // Default output path
+  if (!outputPath) {
+    outputPath = path.join(path.resolve(__dirname, '../..'), 'static', 'img', 'svg');
+  }
+
+  // Ensure the base output directory exists
+  const baseOutputDir = typeof outputPath === 'string' && !path.extname(outputPath) 
+    ? outputPath 
+    : path.dirname(outputPath);
+    
+  if (!fs.existsSync(baseOutputDir)) {
+    fs.mkdirSync(baseOutputDir, { recursive: true });
+    console.log(`[INFO] Created directory: ${baseOutputDir}`);
+  }
+
+  // Resolve icon component
+  let IconComponent = icon;
+  let iconIdentifier = null;
+  
+  if (typeof icon === 'string') {
+
+    if (icon.includes('/')) {
+
+      // ("ai/AiFillAlert")
+      IconComponent = requireDynamicIcon(icon);
+      iconIdentifier = icon.split('/')[1];
+
+    } else {
+
+      // Icon from the iconMap
+      IconComponent = iconMap[icon.toLowerCase()]?.icon;
+      iconIdentifier = icon;
+    }
+    
+    if (!IconComponent) {
+      throw new Error(`Icon "${icon}" could not be resolved`);
+    }
+    
+    // Use identifier if iconName not specified
+    if (!options.iconName && iconIdentifier) {
+      options.iconName = iconIdentifier;
+    }
+  }
+  
+  const { color = 'white', size = 24, filename = null, iconName = null } = options;
+  
+  // Determine final output path
+  const pathStats = fs.existsSync(outputPath) ? fs.statSync(outputPath) : null;
+  const isDirectory = pathStats ? pathStats.isDirectory() : false;
+  
+  if (isDirectory || filename) {
+    const baseDir = isDirectory ? outputPath : path.dirname(outputPath);
+    
+    // Create directory if needed
+    if (!fs.existsSync(baseDir)) {
+      fs.mkdirSync(baseDir, { recursive: true });
+    }
+    
+    // Generate filename if not provided
+    const componentName = iconName || IconComponent.name;
+    const finalFilename = filename || `icon-${componentName}.svg`;
+    outputPath = path.join(baseDir, finalFilename);
+  }
+  
+  // Create and render the icon
+  const element = React.createElement(IconComponent, { 
+    color, 
+    size,
+    style: { color }
+  });
+  
+  // Render the React element to an HTML string and clean it
+  const svgString = ReactDOMServer.renderToStaticMarkup(element);
+  const cleanedSvg = cleanSvgString(svgString, color);
+  
+  // Ensure final output path exists
+  const finalDir = path.dirname(outputPath);
+
+  if (!fs.existsSync(finalDir)) {
+    fs.mkdirSync(finalDir, { recursive: true });
+  }
+  
+  // Write to file
+  fs.writeFileSync(outputPath, cleanedSvg);
+  console.log(`[INFO] Generated SVG icon: ${outputPath}`);
+  
+  return outputPath;
+}
+
+module.exports = { extractSvg, iconMap };

package/src/utils/imageDownloader.js

@@ -0,0 +1,88 @@
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+
+// AI GENERATED - Partially
+
+/**
+ * Downloads or copies an image from a URL or local file path to a specified directory
+ * 
+ * @param {string} source - The URL or local file path of the image
+ * @param {string} outputDir - The directory where the image should be saved
+ * @param {string} [filename='temp_image.png'] - The filename to use for the saved image
+ * @returns {Promise<string>} - A promise that resolves with the path to the saved image
+ */
+async function downloadImage(source, outputDir, filename = 'temp_image.png') {
+
+  const tmpImagePath = path.resolve(outputDir, filename);
+  
+  // Check if the source is a local file path or a URL
+  const isUrl = source.startsWith('http://') || source.startsWith('https://');
+  
+  if (isUrl) {
+    console.log(`[INFO] Downloading remote image from: ${source}`);
+    
+    return new Promise((resolve, reject) => {
+      const file = fs.createWriteStream(tmpImagePath);
+      
+      https.get(source, (response) => {
+        if (response.statusCode !== 200) {
+          reject(new Error(`Failed to download image, status code: ${response.statusCode}`));
+          return;
+        }
+        
+        response.pipe(file);
+        
+        file.on('finish', () => {
+          file.close();
+          resolve(tmpImagePath);
+        });
+        
+        file.on('error', (err) => {
+          fs.unlink(tmpImagePath, () => {});
+          reject(err);
+        });
+      }).on('error', (err) => {
+        fs.unlink(tmpImagePath, () => {});
+        reject(err);
+      });
+    });
+  } else {
+
+    // local file path
+    console.log(`[INFO] Copying local image from: ${source}`);
+    
+    return new Promise((resolve, reject) => {
+
+      // Check if source file exists
+      if (!fs.existsSync(source)) {
+        reject(new Error(`Source file does not exist: ${source}`));
+        return;
+      }
+      
+      // Create a read stream from the source file
+      const readStream = fs.createReadStream(source);
+      const writeStream = fs.createWriteStream(tmpImagePath);
+      
+      // Pipe the read stream to the write stream
+      readStream.pipe(writeStream);
+      
+      writeStream.on('finish', () => {
+        resolve(tmpImagePath);
+      });
+      
+      writeStream.on('error', (err) => {
+        fs.unlink(tmpImagePath, () => {});
+        reject(err);
+      });
+      
+      readStream.on('error', (err) => {
+        fs.unlink(tmpImagePath, () => {});
+        reject(err);
+      });
+    });
+  }
+}
+
+module.exports = { downloadImage };

package/src/utils/imageProcessor.js

@@ -0,0 +1,134 @@
+const sharp = require('sharp');
+
+// AI GENERATED
+
+/**
+ * Reshapes an image to various predefined shapes
+ * 
+ * @param {string} imagePath - Path to the input image
+ * @param {string} outputPath - Path to save the processed image
+ * @param {string} [shape='circle'] - Shape to apply ('circle', 'square', 'rounded', 'hexagon', 'shield')
+ * @param {number} [roundedCornerRadius=50] - Corner radius for rounded shape (percentage)
+ * @returns {Promise<string>} - A promise that resolves with the path to the processed image
+ */
+async function reshapeImage(imagePath, outputPath, shape = 'circle', roundedCornerRadius = 50) {
+  console.log(`[INFO] Processing image to ${shape} shape...`);
+  
+  try {
+    // Get image dimensions
+    const metadata = await sharp(imagePath).metadata();
+    const size = Math.min(metadata.width, metadata.height);
+    
+    let shapeMask;
+    
+    switch (shape.toLowerCase()) {
+      case 'circle':
+        shapeMask = Buffer.from(
+          `<svg><circle cx="${size/2}" cy="${size/2}" r="${size/2}" fill="white"/></svg>`
+        );
+        break;
+        
+      case 'square':
+        // No mask needed for square, just resize to equal width/height
+        await sharp(imagePath)
+          .resize(size, size, { fit: 'cover' })
+          .toFile(outputPath);
+        return outputPath;
+        
+      case 'rounded':
+        // Convert percentage to actual pixels (e.g., 50% becomes size/4)
+        const radius = Math.min(100, Math.max(0, roundedCornerRadius)) * size / 200;
+        shapeMask = Buffer.from(
+          `<svg><rect x="0" y="0" width="${size}" height="${size}" rx="${radius}" ry="${radius}" fill="white"/></svg>`
+        );
+        break;
+        
+      case 'hexagon':
+        // Calculate hexagon points
+        const centerX = size / 2;
+        const centerY = size / 2;
+        const hexRadius = size / 2;
+        let points = '';
+        for (let i = 0; i < 6; i++) {
+          const angleDeg = 60 * i - 30;
+          const angleRad = Math.PI / 180 * angleDeg;
+          const x = centerX + hexRadius * Math.cos(angleRad);
+          const y = centerY + hexRadius * Math.sin(angleRad);
+          points += `${x},${y} `;
+        }
+        shapeMask = Buffer.from(
+          `<svg><polygon points="${points}" fill="white"/></svg>`
+        );
+        break;
+        
+      case 'shield':
+        const shieldWidth = size;
+        const shieldHeight = size;
+        const bottomCurve = size / 3;
+        shapeMask = Buffer.from(
+          `<svg>
+            <path d="M ${shieldWidth/2},0
+                     L ${shieldWidth},${shieldHeight/3}
+                     C ${shieldWidth},${shieldHeight-bottomCurve} ${shieldWidth/2},${shieldHeight} ${shieldWidth/2},${shieldHeight}
+                     C ${shieldWidth/2},${shieldHeight} 0,${shieldHeight-bottomCurve} 0,${shieldHeight/3}
+                     L ${shieldWidth/2},0 Z" 
+                  fill="white"/>
+          </svg>`
+        );
+        break;
+        
+      default:
+        // Default to circle if shape is not recognized
+        console.warn(`Shape "${shape}" not recognized, defaulting to circle`);
+        shapeMask = Buffer.from(
+          `<svg><circle cx="${size/2}" cy="${size/2}" r="${size/2}" fill="white"/></svg>`
+        );
+    }
+    
+    // Apply the mask and save the final image
+    await sharp(imagePath)
+      .resize(size, size, { fit: 'cover' })
+      .composite([
+        {
+          input: shapeMask,
+          blend: 'dest-in'
+        }
+      ])
+      .png()
+      .toFile(outputPath);
+      
+    return outputPath;
+  } catch (error) {
+    console.error(`Error reshaping image to ${shape}:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Resizes an image while maintaining aspect ratio
+ * 
+ * @param {string} imagePath - Path to the input image
+ * @param {string} outputPath - Path to save the processed image
+ * @param {number} maxWidth - Maximum width of the output image
+ * @param {number} maxHeight - Maximum height of the output image
+ * @returns {Promise<string>} - A promise that resolves with the path to the processed image
+ */
+async function resizeImage(imagePath, outputPath, maxWidth, maxHeight) {
+  console.log(`Resizing image to max ${maxWidth}x${maxHeight}...`);
+  
+  await sharp(imagePath)
+    .resize(maxWidth, maxHeight, {
+      fit: 'inside',
+      withoutEnlargement: true
+    })
+    .toFile(outputPath);
+    
+  return outputPath;
+}
+
+
+
+module.exports = {
+    reshapeImage,
+    resizeImage,
+};

package/src/utils/updateTitle.js

@@ -0,0 +1,107 @@
+import { useEffect, useState } from 'react';
+import { useLocation } from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+// AI Generated
+
+/**
+ * UpdateTitle component that changes the page title based on the section in view
+ * @param {Object} props              - Component props
+ * @param {Object} props.sections     - Map of section IDs to their corresponding titles
+ * @param {string} props.defaultTitle - Default title to use when no section is prominently visible
+ * @param {boolean} props.enabled     - Whether the dynamic title functionality is enabled
+ * @returns {null} This component doesn't render anything visible
+ */
+
+
+export default function UpdateTitle({ 
+  sections = {}, 
+  defaultTitle = null,
+  enabled = true 
+}) {
+  const location = useLocation();
+  const { siteConfig } = useDocusaurusContext();
+  const [currentTitle, setCurrentTitle] = useState(null);
+
+  // Use the provided default title or fall back to site title
+  const effectiveDefaultTitle = defaultTitle || siteConfig.title;
+
+  useEffect(() => {
+
+    // Only run if enabled
+    if (!enabled) return;
+
+    // Use provided sections or default to empty object
+    const sectionTitles = Object.keys(sections).length > 0 
+      ? sections 
+      : {};
+
+    const updateTitle = () => {
+      // Get all sections we want to track
+      const sectionsToTrack = Object.keys(sectionTitles)
+        .map(id => document.getElementById(id))
+        .filter(Boolean);
+      
+      if (sectionsToTrack.length === 0) {
+        // No sections found, use default title
+        setCurrentTitle(effectiveDefaultTitle);
+        return;
+      }
+      
+      // Calculate which section is most visible
+      const viewportHeight = window.innerHeight;
+      let maxVisibleSection = null;
+      let maxVisibleArea = 0;
+      
+      sectionsToTrack.forEach(section => {
+        const rect = section.getBoundingClientRect();
+        const visibleTop = Math.max(0, rect.top);
+        const visibleBottom = Math.min(viewportHeight, rect.bottom);
+        const visibleArea = Math.max(0, visibleBottom - visibleTop);
+        
+        if (visibleArea > maxVisibleArea) {
+          maxVisibleArea = visibleArea;
+          maxVisibleSection = section.id;
+        }
+      });
+      
+      // Update title state based on visible section
+      if (maxVisibleSection && sectionTitles[maxVisibleSection]) {
+        setCurrentTitle(sectionTitles[maxVisibleSection]);
+      } else {
+        setCurrentTitle(effectiveDefaultTitle);
+      }
+    };
+    
+    // Add scroll event listener with throttling
+    let isScrolling = false;
+    const handleScroll = () => {
+      if (!isScrolling) {
+        window.requestAnimationFrame(() => {
+          updateTitle();
+          isScrolling = false;
+        });
+        isScrolling = true;
+      }
+    };
+    
+    window.addEventListener('scroll', handleScroll);
+    
+    // Initial call
+    updateTitle();
+    
+    // Clean up
+    return () => {
+      window.removeEventListener('scroll', handleScroll);
+    };
+  }, [location.pathname, sections, effectiveDefaultTitle, enabled]);
+
+  useEffect(() => {
+    if (currentTitle) {
+      document.title = currentTitle;
+    }
+  }, [currentTitle]);
+
+  // Component doesn't render anything visible
+  return null;
+}