Skip to main content

Why New Folders Are Not Updating on the Front End

When you add a new folder to your Docusaurus documentation (e.g., /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/), but it doesn't appear on the live site, there are several potential causes and solutions. This guide provides comprehensive troubleshooting steps based on real-world scenarios.

1. Empty Folders Are Ignored by Docusaurus​

The Problem​

In Docusaurus, empty directories are automatically ignored in the sidebar generation process. For a folder to appear as a category in an autogenerated sidebar, it must contain at least one valid documentation file (.md or .mdx).

The Solution​

Create at least one markdown file inside the new folder:

# Example: Create an index file
touch /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/index.md

Add some content to the file:

# New Category Test

This is a test category for documentation.

Why This Happens​

Docusaurus uses a file-system-based routing approach. It scans directories during the build process, but empty directories have no content to display, so they're excluded from the sidebar and routing table.

2. Autogenerated Sidebar Configuration​

Understanding Your Configuration​

Your sidebars.js is configured to autogenerate the sidebar:

knowledgeDocusaurusSidebar: [
  { type: 'autogenerated', dirName: 'knowledge/docusaurus' }
],

This configuration tells Docusaurus to:

  • Scan the knowledge/docusaurus directory
  • Automatically generate sidebar items based on the folder structure
  • Skip empty folders or folders without valid markdown files

How Autogeneration Works​

  1. Docusaurus recursively scans the specified directory
  2. Each subfolder becomes a category (if it contains files)
  3. Each markdown file becomes a sidebar item
  4. Files named index.md or README.md become the category's landing page

3. Docker Container File Watching Issues​

The Problem​

Your Docusaurus instance runs inside a Docker container in development mode (npm start). While this mode supports Hot Module Replacement (HMR), file system events (like creating new directories or files) may not always propagate correctly from the host machine to the container's internal file watcher.

Common Symptoms​

  • New files/folders created on the host don't appear in the browser
  • Changes to existing files work fine, but new additions don't
  • The container logs don't show any rebuild activity

Solution 1: Restart the Container​

The simplest solution is to restart the Docker container:

sudo docker restart docusaurus

Wait 30-60 seconds for the container to fully restart, then check the logs:

sudo docker logs --tail 100 docusaurus

Look for messages indicating successful startup:

  • Serving!
  • Project is running at...
  • Compiled successfully

Solution 2: Clear Build Cache and Restart​

If a simple restart doesn't work, clear the Docusaurus build cache:

# Remove build artifacts and cache
sudo docker exec docusaurus rm -rf /app/build /app/.docusaurus

# Restart the container
sudo docker restart docusaurus

# Wait and check logs
sleep 60 && sudo docker logs docusaurus 2>&1 | grep -iE "(success|error|listening|serving|started)" | tail -20

Solution 3: Manual Rebuild Inside Container​

For persistent issues, trigger a manual rebuild:

# Execute build command inside the container
sudo docker exec docusaurus npm run build

# Restart to serve the new build
sudo docker restart docusaurus

4. File Permissions and Ownership​

The Problem​

Sometimes Docker containers run with different user permissions than your host system, which can cause file watching issues.

Check File Permissions​

ls -la /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/

Fix Permissions (if needed)​

# Ensure files are readable by the container
sudo chmod -R 755 /opt/docker-data/apps/docusaurus/site/docs/

5. Volume Mount Verification​

Verify Docker Volume Mounts​

Ensure your Docker container has the correct volume mounts:

sudo docker inspect docusaurus --format '{{range .Mounts}}{{println .Type "\t" .Source "->" .Destination}}{{end}}'

You should see something like:

bind    /opt/docker-data/apps/docusaurus/site -> /app

If the mount is incorrect, you'll need to recreate the container with proper volume mappings.

6. Browser Caching Issues​

The Problem​

Your browser might be caching the old version of the site, preventing you from seeing new changes.

Solutions​

  1. Hard Refresh: Press Ctrl + Shift + R (Linux/Windows) or Cmd + Shift + R (Mac)
  2. Clear Browser Cache: Open DevTools (F12) → Network tab → Check "Disable cache"
  3. Incognito/Private Mode: Open the site in a private browsing window

7. Development vs Production Mode​

Understanding the Difference​

  • Development mode (npm start): Uses HMR, faster rebuilds, but sometimes misses file system changes
  • Production mode (npm run build + npm run serve): Full rebuild, slower, but more reliable

Check Container Command​

Verify what command your container is running:

sudo docker inspect docusaurus --format '{{.Config.Cmd}}'

Switch to Production Build (for testing)​

If development mode is problematic:

# Build production version
sudo docker exec docusaurus npm run build

# Serve production build
sudo docker exec docusaurus npm run serve

8. Numbered Folders and Sidebar Labels​

The Problem​

You renamed your folders to 01-new-category-test and 02-category-test-2 to reorder them, but the numbers disappeared in the sidebar (e.g., "01-new-category-test" became just "New Category Test").

Why This Happens​

Docusaurus automatically strips number prefixes (like 01-, 10-, etc.) from folder names in the sidebar. It uses these numbers solely for sorting purposes.

The Solution: Use _category_.json​

To force a specific label (including numbers like "01."), you must add a _category_.json file inside the folder:

File: /path/to/folder/_category_.json

{
  "label": "01. New Category Test",
  "position": 1,
  "link": {
    "type": "generated-index"
  }
}

After adding this file, you must restart the Docusaurus container (or rebuilding) for the changes to take effect.

9. How to Remove Items from the Sidebar​

The Problem​

You see an unwanted item in your sidebar (e.g., "Docusaurus" or an index page) and want to remove it.

Solution 1: Delete the File​

If the item corresponds to a specific file (e.g., index.md inside a category folder) that you don't need, simply deleting the file will remove it from the autogenerated sidebar.

rm /path/to/file/index.md

Solution 2: Hide via Frontmatter​

If you want to keep the file accessible via URL but hide it from the sidebar, add sidebar_class_name: hidden (if using custom CSS) or use the unlisted property (Docusaurus v3+):

---
unlisted: true
---

or for older versions, you might need to exclude it in sidebars.js (if using manual sidebars) or make it a "draft" (which hides it from production builds completely):

---
draft: true
---

Important: If other parts of your site (like the Navbar) link to this file, use sidebar_class_name: hidden instead of deleting it or using draft: true. Deleting a referenced file will cause the build to fail!

Complete Troubleshooting Checklist​

Follow these steps in order:

Step 1: Verify File Exists​

ls -la /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/
  • Confirm the folder exists
  • Confirm it contains at least one .md or .mdx file

Step 2: Check File Content​

cat /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/index.md
  • File has valid markdown content
  • File has a proper heading (e.g., # Title)

Step 3: Restart Container​

sudo docker restart docusaurus
  • Wait 30-60 seconds
  • Check container is running: sudo docker ps | grep docusaurus

Step 4: Verify Logs​

sudo docker logs --tail 50 docusaurus
  • No error messages
  • See "Compiled successfully" or similar success message

Step 5: Clear Cache (if needed)​

sudo docker exec docusaurus rm -rf /app/build /app/.docusaurus
sudo docker restart docusaurus
  • Wait for rebuild to complete
  • Check logs again

Step 6: Browser Refresh​

  • Hard refresh browser (Ctrl + Shift + R)
  • Clear browser cache
  • Try incognito/private mode

Step 7: Verify Sidebar Configuration​

Check sidebars.js to ensure autogeneration is enabled for your directory:

knowledgeDocusaurusSidebar: [
  { type: 'autogenerated', dirName: 'knowledge/docusaurus' }
],

Step 8: Verify Sidebar Labels​

If the folder name appears correct but the label in the sidebar is missing numbers or formatted incorrectly:

  • Check for _category_.json in the folder.
  • Ensure label property is set correctly (e.g., "01. My Title").
  • Restart container after adding/editing _category_.json.

Real-World Example​

Based on actual troubleshooting session:

# 1. Created new folder
mkdir -p /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/

# 2. Added a file
echo "# Test Category" > /opt/docker-data/apps/docusaurus/site/docs/knowledge/docusaurus/new-category-test/index.md

# 3. Folder didn't appear - cleared cache and restarted
sudo docker exec docusaurus rm -rf /app/build /app/.docusaurus
sudo docker restart docusaurus

# 4. Waited for rebuild
sleep 60 && sudo docker logs docusaurus 2>&1 | tail -50

# 5. Verified it appeared on the frontend

Prevention Tips​

1. Always Add Content Immediately​

When creating a new folder, immediately add at least one markdown file to it.

2. Use Consistent Naming​

  • Use lowercase folder names
  • Use hyphens instead of spaces
  • Avoid special characters

3. Monitor Container Logs​

Keep an eye on Docker logs when making changes:

sudo docker logs -f docusaurus

4. Consider Using Production Builds for Testing​

If development mode is unreliable, periodically test with production builds.

Summary​

Most Common Cause: Empty folders are ignored by Docusaurus.

Quick Fix:

  1. Add a markdown file to the folder
  2. Restart the Docker container: sudo docker restart docusaurus
  3. Hard refresh your browser

Nuclear Option (if nothing else works):

sudo docker exec docusaurus rm -rf /app/build /app/.docusaurus
sudo docker restart docusaurus

This comprehensive guide should help you troubleshoot any issues with new folders not appearing in your Docusaurus documentation site.