docusaurus-plugin-llms 0.2.2 → 0.3.0

package/lib/generator.js

@@ -51,10 +51,11 @@ const processor_1 = require("./processor");
  * @returns Cleaned description suitable for TOC
  */
 function cleanDescriptionForToc(description) {
-    if (!description)
+    if (!(0, utils_1.isNonEmptyString)(description))
         return '';
     // Get just the first line for TOC display
-    const firstLine = description.split('\n')[0];
+    const lines = description.split('\n');
+    const firstLine = lines.length > 0 ? lines[0] : '';
     // Remove heading markers only at the beginning of the line
     // Be careful to only remove actual heading markers (# followed by space at beginning)
     // and not hashtag symbols that are part of the content (inline hashtags)
@@ -71,60 +72,74 @@ function cleanDescriptionForToc(description) {
  * @param includeFullContent - Whether to include full content or just links
  * @param version - Version of the file
  * @param customRootContent - Optional custom content to include at the root level
+ * @param batchSize - Batch size for processing documents (default: 100)
  */
-async function generateLLMFile(docs, outputPath, fileTitle, fileDescription, includeFullContent, version, customRootContent) {
-    console.log(`Generating file: ${outputPath}, version: ${version || 'undefined'}`);
+async function generateLLMFile(docs, outputPath, fileTitle, fileDescription, includeFullContent, version, customRootContent, batchSize = 100) {
+    // Validate path length before proceeding
+    if (!(0, utils_1.validatePathLength)(outputPath)) {
+        throw new Error(`Output path exceeds maximum length: ${outputPath}`);
+    }
+    utils_1.logger.verbose(`Generating file: ${outputPath}, version: ${version || 'undefined'}`);
     const versionInfo = version ? `\n\nVersion: ${version}` : '';
     if (includeFullContent) {
         // Generate full content file with header deduplication
+        // Process documents in batches to prevent memory issues on large sites
         const usedHeaders = new Set();
-        const fullContentSections = docs.map(doc => {
-            // Check if content already starts with the same heading to avoid duplication
-            const trimmedContent = doc.content.trim();
-            const firstLine = trimmedContent.split('\n')[0];
-            // Check if the first line is a heading that matches our title
-            const headingMatch = firstLine.match(/^#+\s+(.+)$/);
-            const firstHeadingText = headingMatch ? headingMatch[1].trim() : null;
-            // Generate unique header using the utility function
-            const uniqueHeader = (0, utils_1.ensureUniqueIdentifier)(doc.title, usedHeaders, (counter, base) => {
-                // Try to make it more descriptive by adding the file path info if available
-                if (doc.path && counter === 2) {
-                    const pathParts = doc.path.split('/');
-                    const folderName = pathParts.length > 1 ? pathParts[pathParts.length - 2] : '';
-                    if (folderName) {
-                        return `(${folderName.charAt(0).toUpperCase() + folderName.slice(1)})`;
+        const fullContentSections = [];
+        // Process documents in batches
+        for (let i = 0; i < docs.length; i += batchSize) {
+            const batch = docs.slice(i, i + batchSize);
+            const batchNumber = Math.floor(i / batchSize) + 1;
+            const totalBatches = Math.ceil(docs.length / batchSize);
+            if (totalBatches > 1) {
+                utils_1.logger.verbose(`Processing batch ${batchNumber}/${totalBatches} (${batch.length} documents)`);
+            }
+            const batchSections = batch.map(doc => {
+                // Check if content already starts with the same heading to avoid duplication
+                const trimmedContent = doc.content.trim();
+                const contentLines = trimmedContent.split('\n');
+                const firstLine = contentLines.length > 0 ? contentLines[0] : '';
+                // Check if the first line is a heading that matches our title
+                const headingMatch = firstLine.match(/^#+\s+(.+)$/);
+                const firstHeadingText = headingMatch ? headingMatch[1].trim() : null;
+                // Generate unique header using the utility function
+                const uniqueHeader = (0, utils_1.ensureUniqueIdentifier)(doc.title, usedHeaders, (counter, base) => {
+                    // Try to make it more descriptive by adding the file path info if available
+                    if ((0, utils_1.isNonEmptyString)(doc.path) && counter === 2) {
+                        const pathParts = doc.path.split('/');
+                        const folderName = pathParts.length >= 2 ? pathParts[pathParts.length - 2] : '';
+                        if ((0, utils_1.isNonEmptyString)(folderName)) {
+                            return `(${folderName.charAt(0).toUpperCase() + folderName.slice(1)})`;
+                        }
                     }
-                }
-                return `(${counter})`;
-            });
-            if (firstHeadingText === doc.title) {
-                // Content already has the same heading, replace it with our unique header if needed
-                if (uniqueHeader !== doc.title) {
+                    return `(${counter})`;
+                });
+                if (firstHeadingText === doc.title) {
+                    // Content already has the same heading, replace it with our unique header
                     const restOfContent = trimmedContent.split('\n').slice(1).join('\n');
                     return `## ${uniqueHeader}
 
 ${restOfContent}`;
                 }
                 else {
-                    // Replace the existing H1 with H2 to comply with llmstxt.org standard
-                    const restOfContent = trimmedContent.split('\n').slice(1).join('\n');
+                    // Content doesn't have the same heading, add our unique H2 header
                     return `## ${uniqueHeader}
 
-${restOfContent}`;
-                }
-            }
-            else {
-                // Content doesn't have the same heading, add our unique H2 header
-                return `## ${uniqueHeader}
-
 ${doc.content}`;
-            }
-        });
+                }
+            });
+            fullContentSections.push(...batchSections);
+        }
         // Use custom root content or default message
         const rootContent = customRootContent || 'This file contains all documentation content in a single document following the llmstxt.org standard.';
         const llmFileContent = (0, utils_1.createMarkdownContent)(fileTitle, `${fileDescription}${versionInfo}`, `${rootContent}\n\n${fullContentSections.join('\n\n---\n\n')}`, true // include metadata (description)
         );
-        await (0, utils_1.writeFile)(outputPath, llmFileContent);
+        try {
+            await (0, utils_1.writeFile)(outputPath, llmFileContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${outputPath}: ${(0, utils_1.getErrorMessage)(error)}`);
+        }
     }
     else {
         // Generate links-only file
@@ -137,9 +152,14 @@ ${doc.content}`;
         const rootContent = customRootContent || 'This file contains links to documentation sections following the llmstxt.org standard.';
         const llmFileContent = (0, utils_1.createMarkdownContent)(fileTitle, `${fileDescription}${versionInfo}`, `${rootContent}\n\n## Table of Contents\n\n${tocItems.join('\n')}`, true // include metadata (description)
         );
-        await (0, utils_1.writeFile)(outputPath, llmFileContent);
+        try {
+            await (0, utils_1.writeFile)(outputPath, llmFileContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${outputPath}: ${(0, utils_1.getErrorMessage)(error)}`);
+        }
     }
-    console.log(`Generated: ${outputPath}`);
+    utils_1.logger.info(`Generated: ${outputPath}`);
 }
 /**
  * Generate individual markdown files for each document
@@ -148,42 +168,100 @@ ${doc.content}`;
  * @param siteUrl - Base site URL
  * @param docsDir - The configured docs directory name (e.g., 'docs', 'documentation', etc.)
  * @param keepFrontMatter - Array of frontmatter keys to preserve in generated files
+ * @param preserveDirectoryStructure - Whether to preserve the full directory structure (default: true)
  * @returns Updated docs with new URLs pointing to generated markdown files
  */
-async function generateIndividualMarkdownFiles(docs, outputDir, siteUrl, docsDir = 'docs', keepFrontMatter = []) {
+async function generateIndividualMarkdownFiles(docs, outputDir, siteUrl, docsDir = 'docs', keepFrontMatter = [], preserveDirectoryStructure = true) {
     const updatedDocs = [];
     const usedPaths = new Set();
     for (const doc of docs) {
-        // Use the original path structure, cleaning it up for file system use
+        // Use the original path structure as default filename.
         let relativePath = doc.path
             .replace(/^\/+/, '') // Remove leading slashes
             .replace(/\.mdx?$/, '.md'); // Ensure .md extension
-        relativePath = relativePath
-            .replace(new RegExp(`^${docsDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`), ''); // Remove configured docs dir prefix
+        // Strip the docsDir prefix only if preserveDirectoryStructure is false
+        if (!preserveDirectoryStructure) {
+            relativePath = relativePath
+                .replace(new RegExp(`^${docsDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`), ''); // Remove configured docs dir prefix
+        }
+        // If frontmatter has slug, use that.
+        if ((0, utils_1.isNonEmptyString)(doc.frontMatter?.slug)) {
+            const slug = doc.frontMatter.slug.trim().replace(/^\/+|\/+$/g, ''); // Trim whitespace and slashes
+            if ((0, utils_1.isNonEmptyString)(slug)) { // Only process if slug is not empty after trimming
+                if (slug.includes('/')) {
+                    // Nested slug: create directory structure
+                    relativePath = slug + '.md';
+                }
+                else {
+                    // Simple slug: replace just the filename
+                    const pathParts = relativePath.replace(/\.md$/, '').split('/');
+                    pathParts[pathParts.length - 1] = slug;
+                    relativePath = pathParts.join('/') + '.md';
+                }
+            }
+        }
+        // Otherwise, if frontmatter has id, use that.
+        else if ((0, utils_1.isNonEmptyString)(doc.frontMatter?.id)) {
+            const id = doc.frontMatter.id.trim().replace(/^\/+|\/+$/g, ''); // Trim whitespace and slashes
+            if ((0, utils_1.isNonEmptyString)(id)) { // Only process if id is not empty after trimming
+                if (id.includes('/')) {
+                    // Nested id: create directory structure
+                    relativePath = id + '.md';
+                }
+                else {
+                    // Simple id: replace just the filename
+                    const pathParts = relativePath.replace(/\.md$/, '').split('/');
+                    pathParts[pathParts.length - 1] = id;
+                    relativePath = pathParts.join('/') + '.md';
+                }
+            }
+        }
+        // Trim any leading/trailing whitespace from the path
+        relativePath = relativePath.trim();
         // If path is empty or invalid, create a fallback path
-        if (!relativePath || relativePath === '.md') {
+        if (!(0, utils_1.isNonEmptyString)(relativePath) || relativePath === '.md') {
             const sanitizedTitle = (0, utils_1.sanitizeForFilename)(doc.title, 'untitled');
             relativePath = `${sanitizedTitle}.md`;
         }
         // Ensure path uniqueness
         let uniquePath = relativePath;
         let counter = 1;
+        const MAX_PATH_ITERATIONS = 10000;
+        let pathIterations = 0;
         while (usedPaths.has(uniquePath.toLowerCase())) {
             counter++;
             const pathParts = relativePath.split('.');
             const extension = pathParts.pop() || 'md';
             const basePath = pathParts.join('.');
             uniquePath = `${basePath}-${counter}.${extension}`;
+            pathIterations++;
+            if (pathIterations >= MAX_PATH_ITERATIONS) {
+                // Fallback to timestamp
+                const timestamp = Date.now();
+                uniquePath = `${basePath}-${timestamp}.${extension}`;
+                utils_1.logger.warn(`Maximum iterations reached for unique path. Using timestamp: ${uniquePath}`);
+                break;
+            }
         }
         usedPaths.add(uniquePath.toLowerCase());
-        // Create the full file path and ensure directory exists
-        const fullPath = path.join(outputDir, uniquePath);
+        // Create the full file path and validate/shorten if needed
+        let fullPath = path.join(outputDir, uniquePath);
+        fullPath = (0, utils_1.shortenPathIfNeeded)(fullPath, outputDir, uniquePath);
+        // Update uniquePath to reflect the shortened path if it was changed
+        if (fullPath !== path.join(outputDir, uniquePath)) {
+            uniquePath = path.relative(outputDir, fullPath);
+        }
         const directory = path.dirname(fullPath);
         // Create directory structure if it doesn't exist
-        await fs.mkdir(directory, { recursive: true });
+        try {
+            await fs.mkdir(directory, { recursive: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to create directory ${directory}: ${(0, utils_1.getErrorMessage)(error)}`);
+        }
         // Extract preserved frontmatter if specified
         let preservedFrontMatter = {};
-        if (keepFrontMatter.length > 0 && doc.frontMatter) {
+        if ((0, utils_1.isNonEmptyArray)(keepFrontMatter) && (0, utils_1.isDefined)(doc.frontMatter)) {
             for (const key of keepFrontMatter) {
                 if (key in doc.frontMatter) {
                     preservedFrontMatter[key] = doc.frontMatter[key];
@@ -194,17 +272,22 @@ async function generateIndividualMarkdownFiles(docs, outputDir, siteUrl, docsDir
         const markdownContent = (0, utils_1.createMarkdownContent)(doc.title, doc.description, doc.content, true, // includeMetadata
         Object.keys(preservedFrontMatter).length > 0 ? preservedFrontMatter : undefined);
         // Write the markdown file
-        await (0, utils_1.writeFile)(fullPath, markdownContent);
+        try {
+            await (0, utils_1.writeFile)(fullPath, markdownContent);
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${fullPath}: ${(0, utils_1.getErrorMessage)(error)}`);
+        }
         // Create updated DocInfo with new URL pointing to the generated markdown file
         // Convert file path to URL path (use forward slashes)
-        const urlPath = uniquePath.replace(/\\/g, '/');
+        const urlPath = (0, utils_1.normalizePath)(uniquePath);
         const newUrl = `${siteUrl}/${urlPath}`;
         updatedDocs.push({
             ...doc,
             url: newUrl,
             path: `/${urlPath}` // Update path to the new markdown file
         });
-        console.log(`Generated markdown file: ${uniquePath}`);
+        utils_1.logger.verbose(`Generated markdown file: ${uniquePath}`);
     }
     return updatedDocs;
 }
@@ -215,31 +298,38 @@ async function generateIndividualMarkdownFiles(docs, outputDir, siteUrl, docsDir
  */
 async function generateStandardLLMFiles(context, allDocFiles) {
     const { outDir, siteUrl, docTitle, docDescription, options } = context;
-    const { generateLLMsTxt, generateLLMsFullTxt, llmsTxtFilename = 'llms.txt', llmsFullTxtFilename = 'llms-full.txt', includeOrder = [], includeUnmatchedLast = true, version, generateMarkdownFiles = false, rootContent, fullRootContent } = options;
+    const { generateLLMsTxt, generateLLMsFullTxt, llmsTxtFilename = 'llms.txt', llmsFullTxtFilename = 'llms-full.txt', includeOrder = [], includeUnmatchedLast = true, version, generateMarkdownFiles = false, rootContent, fullRootContent, processingBatchSize = 100 } = options;
     if (!generateLLMsTxt && !generateLLMsFullTxt) {
+        utils_1.logger.warn('No standard LLM files configured for generation. Skipping.');
         return;
     }
     // Process files for the standard outputs
     let processedDocs = await (0, processor_1.processFilesWithPatterns)(context, allDocFiles, [], // No specific include patterns - include all
     [], // No additional ignore patterns beyond global ignoreFiles
     includeOrder, includeUnmatchedLast);
-    console.log(`Processed ${processedDocs.length} documentation files for standard LLM files`);
+    utils_1.logger.verbose(`Processed ${processedDocs.length} documentation files for standard LLM files`);
+    // Check if we have documents to process
+    if (!(0, utils_1.isNonEmptyArray)(processedDocs)) {
+        utils_1.logger.warn('No documents found matching patterns for standard LLM files. Skipping.');
+        return;
+    }
     // Generate individual markdown files if requested
-    if (generateMarkdownFiles && processedDocs.length > 0) {
-        console.log('Generating individual markdown files...');
-        processedDocs = await generateIndividualMarkdownFiles(processedDocs, outDir, siteUrl, context.docsDir, context.options.keepFrontMatter || []);
+    if (generateMarkdownFiles) {
+        utils_1.logger.info('Generating individual markdown files...');
+        processedDocs = await generateIndividualMarkdownFiles(processedDocs, outDir, siteUrl, context.docsDir, context.options.keepFrontMatter || [], context.options.preserveDirectoryStructure !== false // Default to true
+        );
     }
     // Generate llms.txt
     if (generateLLMsTxt) {
         const llmsTxtPath = path.join(outDir, llmsTxtFilename);
         await generateLLMFile(processedDocs, llmsTxtPath, docTitle, docDescription, false, // links only
-        version, rootContent);
+        version, rootContent, processingBatchSize);
     }
     // Generate llms-full.txt
     if (generateLLMsFullTxt) {
         const llmsFullTxtPath = path.join(outDir, llmsFullTxtFilename);
         await generateLLMFile(processedDocs, llmsFullTxtPath, docTitle, docDescription, true, // full content
-        version, fullRootContent);
+        version, fullRootContent, processingBatchSize);
     }
 }
 /**
@@ -249,13 +339,14 @@ async function generateStandardLLMFiles(context, allDocFiles) {
  */
 async function generateCustomLLMFiles(context, allDocFiles) {
     const { outDir, siteUrl, docTitle, docDescription, options } = context;
-    const { customLLMFiles = [], ignoreFiles = [], generateMarkdownFiles = false } = options;
+    const { customLLMFiles = [], ignoreFiles = [], generateMarkdownFiles = false, processingBatchSize = 100 } = options;
     if (customLLMFiles.length === 0) {
+        utils_1.logger.warn('No custom LLM files configured. Skipping.');
         return;
     }
-    console.log(`Generating ${customLLMFiles.length} custom LLM files...`);
+    utils_1.logger.info(`Generating ${customLLMFiles.length} custom LLM files...`);
     for (const customFile of customLLMFiles) {
-        console.log(`Processing custom file: ${customFile.filename}, version: ${customFile.version || 'undefined'}`);
+        utils_1.logger.verbose(`Processing custom file: ${customFile.filename}, version: ${customFile.version || 'undefined'}`);
         // Combine global ignores with custom ignores
         const combinedIgnores = [...ignoreFiles];
         if (customFile.ignorePatterns) {
@@ -266,19 +357,20 @@ async function generateCustomLLMFiles(context, allDocFiles) {
         if (customDocs.length > 0) {
             // Generate individual markdown files if requested
             if (generateMarkdownFiles) {
-                console.log(`Generating individual markdown files for custom file: ${customFile.filename}...`);
-                customDocs = await generateIndividualMarkdownFiles(customDocs, outDir, siteUrl, context.docsDir, context.options.keepFrontMatter || []);
+                utils_1.logger.info(`Generating individual markdown files for custom file: ${customFile.filename}...`);
+                customDocs = await generateIndividualMarkdownFiles(customDocs, outDir, siteUrl, context.docsDir, context.options.keepFrontMatter || [], context.options.preserveDirectoryStructure !== false // Default to true
+                );
             }
             // Use custom title/description or fall back to defaults
             const customTitle = customFile.title || docTitle;
             const customDescription = customFile.description || docDescription;
             // Generate the custom LLM file
             const customFilePath = path.join(outDir, customFile.filename);
-            await generateLLMFile(customDocs, customFilePath, customTitle, customDescription, customFile.fullContent, customFile.version, customFile.rootContent);
-            console.log(`Generated custom LLM file: ${customFile.filename} with ${customDocs.length} documents`);
+            await generateLLMFile(customDocs, customFilePath, customTitle, customDescription, customFile.fullContent, customFile.version, customFile.rootContent, processingBatchSize);
+            utils_1.logger.info(`Generated custom LLM file: ${customFile.filename} with ${customDocs.length} documents`);
         }
         else {
-            console.warn(`No matching documents found for custom LLM file: ${customFile.filename}`);
+            utils_1.logger.warn(`No matching documents found for custom LLM file: ${customFile.filename}`);
         }
     }
 }
@@ -289,18 +381,18 @@ async function generateCustomLLMFiles(context, allDocFiles) {
  */
 async function collectDocFiles(context) {
     const { siteDir, docsDir, options } = context;
-    const { ignoreFiles = [], includeBlog = false } = options;
+    const { ignoreFiles = [], includeBlog = false, warnOnIgnoredFiles = false } = options;
     const allDocFiles = [];
     // Process docs directory
     const fullDocsDir = path.join(siteDir, docsDir);
     try {
         await fs.access(fullDocsDir);
         // Collect all markdown files from docs directory
-        const docFiles = await (0, utils_1.readMarkdownFiles)(fullDocsDir, siteDir, ignoreFiles);
+        const docFiles = await (0, utils_1.readMarkdownFiles)(fullDocsDir, siteDir, ignoreFiles, docsDir, warnOnIgnoredFiles);
         allDocFiles.push(...docFiles);
     }
     catch (err) {
-        console.warn(`Docs directory not found: ${fullDocsDir}`);
+        utils_1.logger.warn(`Docs directory not found: ${fullDocsDir}`);
     }
     // Process blog if enabled
     if (includeBlog) {
@@ -308,11 +400,11 @@ async function collectDocFiles(context) {
         try {
             await fs.access(blogDir);
             // Collect all markdown files from blog directory
-            const blogFiles = await (0, utils_1.readMarkdownFiles)(blogDir, siteDir, ignoreFiles);
+            const blogFiles = await (0, utils_1.readMarkdownFiles)(blogDir, siteDir, ignoreFiles, docsDir, warnOnIgnoredFiles);
             allDocFiles.push(...blogFiles);
         }
         catch (err) {
-            console.warn(`Blog directory not found: ${blogDir}`);
+            utils_1.logger.warn(`Blog directory not found: ${blogDir}`);
         }
     }
     return allDocFiles;

package/lib/index.js

@@ -11,6 +11,159 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = docusaurusPluginLLMs;
 const generator_1 = require("./generator");
+const utils_1 = require("./utils");
+/**
+ * Validates plugin options to ensure they conform to expected types and constraints
+ * @param options - Plugin options to validate
+ * @throws Error if any option is invalid
+ */
+function validatePluginOptions(options) {
+    // Validate includeOrder
+    if (options.includeOrder !== undefined) {
+        if (!Array.isArray(options.includeOrder)) {
+            throw new Error('includeOrder must be an array');
+        }
+        if (!options.includeOrder.every(item => typeof item === 'string')) {
+            throw new Error('includeOrder must contain only strings');
+        }
+    }
+    // Validate ignoreFiles
+    if (options.ignoreFiles !== undefined) {
+        if (!Array.isArray(options.ignoreFiles)) {
+            throw new Error('ignoreFiles must be an array');
+        }
+        if (!options.ignoreFiles.every(item => typeof item === 'string')) {
+            throw new Error('ignoreFiles must contain only strings');
+        }
+    }
+    // Validate pathTransformation
+    if ((0, utils_1.isDefined)(options.pathTransformation)) {
+        if (typeof options.pathTransformation !== 'object') {
+            throw new Error('pathTransformation must be an object');
+        }
+        const { ignorePaths, addPaths } = options.pathTransformation;
+        if (ignorePaths !== undefined) {
+            if (!Array.isArray(ignorePaths)) {
+                throw new Error('pathTransformation.ignorePaths must be an array');
+            }
+            if (!ignorePaths.every(item => typeof item === 'string')) {
+                throw new Error('pathTransformation.ignorePaths must contain only strings');
+            }
+        }
+        if (addPaths !== undefined) {
+            if (!Array.isArray(addPaths)) {
+                throw new Error('pathTransformation.addPaths must be an array');
+            }
+            if (!addPaths.every(item => typeof item === 'string')) {
+                throw new Error('pathTransformation.addPaths must contain only strings');
+            }
+        }
+    }
+    // Validate boolean options
+    const booleanOptions = [
+        'generateLLMsTxt',
+        'generateLLMsFullTxt',
+        'includeBlog',
+        'includeUnmatchedLast',
+        'excludeImports',
+        'removeDuplicateHeadings',
+        'generateMarkdownFiles',
+        'preserveDirectoryStructure'
+    ];
+    for (const option of booleanOptions) {
+        if (options[option] !== undefined && typeof options[option] !== 'boolean') {
+            throw new Error(`${option} must be a boolean`);
+        }
+    }
+    // Validate string options
+    const stringOptions = [
+        'docsDir',
+        'title',
+        'description',
+        'llmsTxtFilename',
+        'llmsFullTxtFilename',
+        'version',
+        'rootContent',
+        'fullRootContent'
+    ];
+    for (const option of stringOptions) {
+        if (options[option] !== undefined && typeof options[option] !== 'string') {
+            throw new Error(`${option} must be a string`);
+        }
+    }
+    // Validate keepFrontMatter
+    if (options.keepFrontMatter !== undefined) {
+        if (!Array.isArray(options.keepFrontMatter)) {
+            throw new Error('keepFrontMatter must be an array');
+        }
+        if (!options.keepFrontMatter.every(item => typeof item === 'string')) {
+            throw new Error('keepFrontMatter must contain only strings');
+        }
+    }
+    // Validate logLevel
+    if (options.logLevel !== undefined) {
+        const validLogLevels = ['quiet', 'normal', 'verbose'];
+        if (!validLogLevels.includes(options.logLevel)) {
+            throw new Error(`logLevel must be one of: ${validLogLevels.join(', ')}`);
+        }
+    }
+    // Validate customLLMFiles
+    if (options.customLLMFiles !== undefined) {
+        if (!Array.isArray(options.customLLMFiles)) {
+            throw new Error('customLLMFiles must be an array');
+        }
+        options.customLLMFiles.forEach((file, index) => {
+            if (!(0, utils_1.isDefined)(file) || typeof file !== 'object') {
+                throw new Error(`customLLMFiles[${index}] must be an object`);
+            }
+            // Required fields
+            if (!(0, utils_1.isNonEmptyString)(file.filename)) {
+                throw new Error(`customLLMFiles[${index}].filename must be a non-empty string`);
+            }
+            if (!(0, utils_1.isNonEmptyArray)(file.includePatterns)) {
+                throw new Error(`customLLMFiles[${index}].includePatterns must be a non-empty array`);
+            }
+            if (!file.includePatterns.every(item => typeof item === 'string')) {
+                throw new Error(`customLLMFiles[${index}].includePatterns must contain only strings`);
+            }
+            if (typeof file.fullContent !== 'boolean') {
+                throw new Error(`customLLMFiles[${index}].fullContent must be a boolean`);
+            }
+            // Optional fields
+            if ((0, utils_1.isDefined)(file.title) && !(0, utils_1.isNonEmptyString)(file.title)) {
+                throw new Error(`customLLMFiles[${index}].title must be a non-empty string`);
+            }
+            if ((0, utils_1.isDefined)(file.description) && !(0, utils_1.isNonEmptyString)(file.description)) {
+                throw new Error(`customLLMFiles[${index}].description must be a non-empty string`);
+            }
+            if (file.ignorePatterns !== undefined) {
+                if (!Array.isArray(file.ignorePatterns)) {
+                    throw new Error(`customLLMFiles[${index}].ignorePatterns must be an array`);
+                }
+                if (!file.ignorePatterns.every(item => typeof item === 'string')) {
+                    throw new Error(`customLLMFiles[${index}].ignorePatterns must contain only strings`);
+                }
+            }
+            if (file.orderPatterns !== undefined) {
+                if (!Array.isArray(file.orderPatterns)) {
+                    throw new Error(`customLLMFiles[${index}].orderPatterns must be an array`);
+                }
+                if (!file.orderPatterns.every(item => typeof item === 'string')) {
+                    throw new Error(`customLLMFiles[${index}].orderPatterns must contain only strings`);
+                }
+            }
+            if (file.includeUnmatchedLast !== undefined && typeof file.includeUnmatchedLast !== 'boolean') {
+                throw new Error(`customLLMFiles[${index}].includeUnmatchedLast must be a boolean`);
+            }
+            if ((0, utils_1.isDefined)(file.version) && !(0, utils_1.isNonEmptyString)(file.version)) {
+                throw new Error(`customLLMFiles[${index}].version must be a non-empty string`);
+            }
+            if ((0, utils_1.isDefined)(file.rootContent) && !(0, utils_1.isNonEmptyString)(file.rootContent)) {
+                throw new Error(`customLLMFiles[${index}].rootContent must be a non-empty string`);
+            }
+        });
+    }
+}
 /**
  * A Docusaurus plugin to generate LLM-friendly documentation following
  * the llmstxt.org standard
@@ -20,13 +173,24 @@ const generator_1 = require("./generator");
  * @returns Plugin object
  */
 function docusaurusPluginLLMs(context, options = {}) {
+    // Validate options before processing
+    validatePluginOptions(options);
     // Set default options
-    const { generateLLMsTxt = true, generateLLMsFullTxt = true, docsDir = 'docs', ignoreFiles = [], title, description, llmsTxtFilename = 'llms.txt', llmsFullTxtFilename = 'llms-full.txt', includeBlog = false, pathTransformation, includeOrder = [], includeUnmatchedLast = true, customLLMFiles = [], excludeImports = false, removeDuplicateHeadings = false, generateMarkdownFiles = false, keepFrontMatter = [], rootContent, fullRootContent, } = options;
+    const { generateLLMsTxt = true, generateLLMsFullTxt = true, docsDir = 'docs', ignoreFiles = [], title, description, llmsTxtFilename = 'llms.txt', llmsFullTxtFilename = 'llms-full.txt', includeBlog = false, pathTransformation, includeOrder = [], includeUnmatchedLast = true, customLLMFiles = [], excludeImports = false, removeDuplicateHeadings = false, generateMarkdownFiles = false, keepFrontMatter = [], rootContent, fullRootContent, logLevel = 'normal', } = options;
+    // Initialize logging level
+    const logLevelMap = {
+        quiet: utils_1.LogLevel.QUIET,
+        normal: utils_1.LogLevel.NORMAL,
+        verbose: utils_1.LogLevel.VERBOSE,
+    };
+    (0, utils_1.setLogLevel)(logLevelMap[logLevel] || utils_1.LogLevel.NORMAL);
     const { siteDir, siteConfig, outDir, } = context;
-    // Build the site URL with proper trailing slash
-    const siteUrl = siteConfig.url + (siteConfig.baseUrl.endsWith('/')
-        ? siteConfig.baseUrl.slice(0, -1)
-        : siteConfig.baseUrl || '');
+    // Normalize baseUrl: remove trailing slash unless it's root '/'
+    let normalizedBaseUrl = siteConfig.baseUrl || '/';
+    if (normalizedBaseUrl !== '/' && normalizedBaseUrl.endsWith('/')) {
+        normalizedBaseUrl = normalizedBaseUrl.slice(0, -1);
+    }
+    const siteUrl = siteConfig.url + normalizedBaseUrl;
     // Create a plugin context object with processed options
     const pluginContext = {
         siteDir,
@@ -63,7 +227,7 @@ function docusaurusPluginLLMs(context, options = {}) {
          * Generates LLM-friendly documentation files after the build is complete
          */
         async postBuild(props) {
-            console.log('Generating LLM-friendly documentation...');
+            utils_1.logger.info('Generating LLM-friendly documentation...');
             try {
                 let enhancedContext = pluginContext;
                 // If props are provided (Docusaurus 3.x+), use the resolved routes
@@ -96,8 +260,8 @@ function docusaurusPluginLLMs(context, options = {}) {
                 // Collect all document files
                 const allDocFiles = await (0, generator_1.collectDocFiles)(enhancedContext);
                 // Skip further processing if no documents were found
-                if (allDocFiles.length === 0) {
-                    console.warn('No documents found to process.');
+                if (!(0, utils_1.isNonEmptyArray)(allDocFiles)) {
+                    utils_1.logger.warn('No documents found to process. Skipping.');
                     return;
                 }
                 // Process standard LLM files (llms.txt and llms-full.txt)
@@ -105,10 +269,10 @@ function docusaurusPluginLLMs(context, options = {}) {
                 // Process custom LLM files
                 await (0, generator_1.generateCustomLLMFiles)(enhancedContext, allDocFiles);
                 // Output overall statistics
-                console.log(`Stats: ${allDocFiles.length} total available documents processed`);
+                utils_1.logger.info(`Stats: ${allDocFiles.length} total available documents processed`);
             }
             catch (err) {
-                console.error('Error generating LLM documentation:', err);
+                utils_1.logger.error(`Error generating LLM documentation: ${(0, utils_1.getErrorMessage)(err)}`);
             }
         },
     };