Troubleshooting Guide

This guide helps you resolve common issues you may encounter when using LeafMove Smart Documentation Center.

🔧 Installation and Configuration Issues

Node.js Version Issues

Problem: Runtime error indicating Node.js version is too low

Solution:

# Check current version
node --version

# If version is below 16.0.0, please upgrade Node.js
# Recommended to use nvm to manage Node.js versions
nvm install 18
nvm use 18

Dependency Installation Failures

Problem: npm install execution fails

Solution:

# Clear npm cache
npm cache clean --force

# Delete node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall
npm install

VuePress Configuration Errors

Problem: bundler.dev is not a function error

Solution:

// Ensure correct import and usage of bundler
import { viteBundler } from '@vuepress/bundler-vite'

export default defineUserConfig({
  bundler: viteBundler(), // Note: must call the function
})

🚀 Build and Deployment Issues

Build Failures

Problem: npm run docs:build fails

Common Causes and Solutions:

  1. Insufficient Memory:

    # Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npm run docs:build

  2. File Path Issues:

    # Check if file paths are correct
# Ensure all links use relative paths

  3. Plugin Conflicts:

    // Temporarily disable plugins for testing
plugins: [
  // searchPlugin({...})  // Comment out plugins
]

GitHub Pages Deployment Failures

Problem: GitHub Actions deployment fails

Check Steps:

  1. Check GitHub Pages Settings:

    • Ensure GitHub Pages is enabled in repository settings
    • Select "GitHub Actions" as deployment source

  2. Check Workflow Permissions:

    permissions:
  contents: read
  pages: write
  id-token: write

  3. Check Build Output:

    # Test build locally
npm run docs:build
ls -la docs/.vuepress/dist/

Custom Domain Issues

Problem: Custom domain cannot be accessed

Solution:

  1. Check DNS configuration
  2. Ensure CNAME file is correct
  3. Wait for DNS propagation (may take 24-48 hours)

🔍 Search Function Issues

Search Not Working

Problem: Search box unresponsive or no results

Solution:

  1. Check Plugin Configuration:

    import { searchPlugin } from '@vuepress/plugin-search'

plugins: [
  searchPlugin({
    locales: {
      '/': {
        placeholder: 'Search Documentation',
      },
      '/en/': {
        placeholder: 'Search Documentation',
      },
    },
  }),
]

  2. Rebuild Index:

    # Clear cache and rebuild
rm -rf docs/.vuepress/.cache
npm run docs:dev

Inaccurate Search Results

Problem: Search results don't match expectations

Solution:

  • Check if document content contains search keywords
  • Confirm document file format is correct
  • Verify search plugin configuration

📝 Document Content Issues

Problem: Links in documents cannot be accessed

Solution:

  1. Check Relative Paths:

    # Correct relative paths
[Link text](./other-file.md)
[Link text](../other-dir/file.md)

# Avoid absolute paths
[Link text](/absolute/path.md)  # May have issues

  2. Check File Existence:

    # Confirm target file actually exists
ls -la docs/path/to/file.md

Images Not Displaying

Problem: Images in documents not showing

Solution:

  1. Use Correct Image Paths:

    # Recommended: Place images in .vuepress/public/ directory
![Image description](/images/screenshot.png)

# Or use relative paths
![Image description](./images/screenshot.png)

  2. Check Image Format:

    • Supported formats: PNG, JPG, GIF, SVG
    • Ensure filenames don't contain special characters

Markdown Rendering Issues

Problem: Markdown format displays abnormally

Solution:

  1. Check Syntax:

    # Correct heading format
## Level 2 Heading

# Correct list format
- List item 1
- List item 2

# Correct code block format
```javascript
console.log('Hello World');

  2. Use Markdown Validation Tools:

🔄 Multi-language Issues

Language Switching Not Working

Problem: Language switching button not working or missing

Solution:

  1. Check Multi-language Configuration:

    export default defineUserConfig({
  locales: {
    '/': {
      lang: 'zh-CN',
      title: 'Chinese Title'
    },
    '/en/': {
      lang: 'en-US',
      title: 'English Title'
    }
  }
})

  2. Check File Structure:

    docs/
├── README.md          # Chinese
├── guide/
└── en/
    ├── README.md      # English
    └── guide/

Missing Language Content

Problem: Some pages missing in specific language

Solution:

  • Ensure corresponding files exist in language directories
  • Check file paths in sidebar configuration
  • Verify language-specific navigation setup

🛠 Performance Issues

Slow Build Speed

Problem: Document build time too long

Solution:

  1. Optimize Images:

    • Compress image file sizes
    • Use appropriate image formats

  2. Reduce Plugins:

    // Only enable necessary plugins
plugins: [
  searchPlugin({...})  // Keep only essential plugins
]

  3. Use Incremental Build:

    # Use hot reload in development mode
npm run docs:dev

Slow Page Loading

Problem: Documentation pages load slowly

Solution:

  1. Enable Caching:

    export default defineUserConfig({
  bundler: viteBundler({
    viteOptions: {
      build: {
        rollupOptions: {
          output: {
            manualChunks: {
              vendor: ['vue', 'vue-router']
            }
          }
        }
      }
    }
  })
})

  2. Optimize Resources:

    • Compress CSS and JavaScript
    • Use CDN for static resources

📞 Getting Help

If the above solutions don't resolve your issue, please get help through:

Community Support

  1. GitHub Issues: Submit Issue
  2. GitHub Discussions: Join Discussion

When Submitting Issues, Please Include

  • Detailed problem description
  • Steps to reproduce
  • Error messages and logs
  • Environment information (OS, Node.js version, etc.)
  • Relevant configuration files

Debug Information Collection

# Collect system information
node --version
npm --version
npm list vuepress

# Collect error logs
npm run docs:build > build.log 2>&1

# Check configuration files
cat docs/.vuepress/config.js