Migration Guide

This guide helps you migrate from other popular documentation systems to doc-system.

Quick Comparison#

Migrating from Docusaurus#

Overview#

Docusaurus and doc-system share similar philosophies but doc-system is more lightweight.

File Structure Mapping#

Docusaurus:

my-website/├── docs/├── blog/├── src/│ └── pages/├── static/├── docusaurus.config.js└── sidebars.js

doc-system:

doc-system/├── docs/├── theme/├── scripts/└── config.json

Configuration Migration#

Docusaurus (docusaurus.config.js):

module.exports ={title:'My Site',tagline:'The tagline of my site',url:'https://mysite.com',baseUrl:'/',favicon:'img/favicon.ico',organizationName:'facebook',projectName:'docusaurus',themeConfig:{navbar:{title:'My Site',links:[{to:'docs/intro',label:'Docs',position:'left'}, ],},footer:{copyright:`Copyright © ${newDate().getFullYear()} My Project`,},},};

doc-system (config.json):

{"title":"My Site","description":"The tagline of my site","baseUrl":"/","navbar":{"title":"My Site","links":[{"label":"Docs","to":"/docs/intro"}]},"footer":{"copyright":"Copyright © 2025 My Project"}}

Sidebar Migration#

Docusaurus (sidebars.js):

module.exports ={docs:['intro','installation',{type:'category',label:'Guides',items:['guides/configuration','guides/deployment'],}, ],};

doc-system (auto-generated from folder structure):

• No manual sidebar configuration needed!
• Just organize your docs/ folder:
  Plaintext

  docs/├── intro.md├── installation.md└── guides/ ├── configuration.md └── deployment.md

Content Migration Steps#

1. Copy markdown files:

   Bash

   # Copy all docscp -r docusaurus-site/docs/* doc-system/docs/

2. Update frontmatter:

   • Both use similar frontmatter
   • Remove Docusaurus-specific fields:
   Markdown

   ---# Keep these:title:Page Titledescription:Page description# Remove these (Docusaurus-specific):id:page-idslug:/custom-urlsidebar_label:Short Namesidebar_position:1---

3. Update MDX to Markdown:

   • doc-system uses pure Markdown (not MDX)
   • Convert React components to HTML/Markdown:

   Docusaurus (MDX):

   Mdx

   import Tabs from '@theme/Tabs';import TabItem from '@theme/TabItem';<Tabs> <TabItem value="js"label="JavaScript"> JavaScript code </TabItem></Tabs>

   doc-system (Markdown):

   Markdown

   **JavaScript:**```javascript// JavaScript code

   Python:

   Python

   # Python code

   Plaintext

4. Update asset paths:

   Markdown

   <!-- Docusaurus -->![Logo](/img/logo.png)<!-- doc-system -->![Logo](images/logo.png)

5. Copy images:

   Bash

   cp -r docusaurus-site/static/img/* doc-system/docs/images/

Features Not in doc-system#

Blog:

• Docusaurus has built-in blog support
• For doc-system,consider adding a separate blog platform

Versioning:

• Docusaurus supports multiple doc versions
• Use Git branches/tags for versioning in doc-system

i18n (Internationalization):

• Not built-in to doc-system
• Consider separate language branches

React Components:

• Docusaurus uses MDX
• Use HTML directly in Markdown instead

Deployment Migration#

Both support GitHub Pages similarly:

Docusaurus:

GIT_USER=<username>npm run deploy

doc-system:

# Uses GitHub Actions (automated)git push origin master

Migrating from VuePress#

Overview#

VuePress and doc-system are both lightweight,but doc-system has no framework dependencies.

Configuration Migration#

VuePress (.vuepress/config.js):

module.exports ={title:'My Site',description:'My description',themeConfig:{nav:[{text:'Home',link:'/'},{text:'Guide',link:'/guide/'}, ],sidebar:['/','/guide/','/config/' ]}}

doc-system (config.json):

{"title":"My Site","description":"My description","navbar":{"title":"My Site","links":[{"label":"Guide","to":"/docs/guide"}]}}

Content Migration Steps#

1. Copy markdown files:

   Bash

   cp -r vuepress-site/docs/* doc-system/docs/

2. Update frontmatter:

   Markdown

   ---# Keep:title:Page Titledescription:Description# Remove (VuePress-specific):sidebar:autosidebarDepth:2---

3. Remove Vue components:

   VuePress:

   Markdown

   <Badgetext="beta"type="warning"/>

   doc-system:

   Markdown

   >**⚠️ Warning:** This feature is in beta

4. Update custom containers:

   VuePress:

   Markdown

   :::tipThis is a tip:::

   doc-system:

   Markdown

   >**💡 Tip:** This is a tip

File Structure Changes#

VuePress:

docs/├── .vuepress/│ ├── config.js│ ├── public/│ └── styles/└── README.md

doc-system:

.├── docs/│ └── intro.md├── theme/│ └── styles.css└── config.json

Migrating from MkDocs#

Overview#

MkDocs is Python-based,doc-system is Node.js-based.

Prerequisites#

Install Node.js:

# If coming from Python/MkDocsnvm install 22nvm use 22

Configuration Migration#

MkDocs (mkdocs.yml):

site_name:MyDocsnav:-Home:index.md-About:about.md-Guides:-Installation:guides/installation.md-Configuration:guides/configuration.mdtheme:name:material

doc-system (config.json):

{"title":"My Docs","navbar":{"title":"My Docs","links":[{"label":"About","to":"/docs/about"}]}}

Content Migration Steps#

1. Copy markdown files:

   Bash

   cp -r mkdocs-site/docs/* doc-system/docs/

2. Rename index.md:

   Bash

   mv docs/index.md docs/intro.md

3. Update admonitions:

   MkDocs:

   Markdown

   !!! note This is a note!!! warning "Custom Title" This is a warning

   doc-system:

   Markdown

   >**📝 Note:** This is a note>**⚠️ Custom Title:** This is a warning

4. Update code blocks:

   • Both use fenced code blocks
   • Syntax is the same:
   Markdown

   ```pythonprint("Hello")

   Plaintext

Deployment Changes#

MkDocs:

mkdocs gh-deploy

doc-system:

# Setup GitHub Actions (one time)# Then just push:git push origin master

Migrating from GitBook#

Overview#

GitBook is a commercial platform,doc-system is open-source and self-hosted.

File Structure#

GitBook:

.├── README.md├── SUMMARY.md└── chapters/ ├── chapter1.md └── chapter2.md

doc-system:

.├── docs/│ ├── intro.md (was README.md)│ └── chapters/│ ├── chapter1.md│ └── chapter2.md├── theme/└── config.json

Migration Steps#

1. Export from GitBook:

   • Go to Settings → Export → GitHub
   • Or manually copy markdown files

2. Restructure files:

   Bash

   mkdir -p doc-system/docscp README.md doc-system/docs/intro.mdcp -r chapters/ doc-system/docs/chapters/

3. Convert SUMMARY.md:

   • GitBook uses SUMMARY.md for navigation
   • doc-system auto-generates from folder structure
   • No manual conversion needed!

4. Update internal links:

   GitBook:

   Markdown

   [Link](chapter1.md)

   doc-system:

   Markdown

   [Link](chapters/chapter1)

Migrating from Read the Docs / Sphinx#

Overview#

Sphinx uses reStructuredText (rST),doc-system uses Markdown.

Convert rST to Markdown#

Use pandoc to convert:

# Install pandoc# Ubuntu/Debian:sudo apt-get install pandoc# Mac:brew install pandoc# Convert all .rst files to .mdfind docs -name "*.rst" -exec sh -c 'pandoc "${0}"-f rst -t markdown -o "${0%.rst}.md"'{}\;

Manual Cleanup#

After conversion,manually fix:

1. Code blocks:

   Rst

   .. code-block::python print("hello")

   Becomes:

   Markdown

   ```pythonprint("hello")

   Plaintext

2. Admonitions:

   Rst

   .. note:: This is a note

   Becomes:

   Markdown

   >**📝 Note:** This is a note

3. Cross-references:

   Rst

   :ref:`installation`

   Becomes:

   Markdown

   [Installation](installation)

General Migration Checklist#

Use this checklist for any migration:

• ◻️ Install Node.js 22.x
• ◻️ Clone doc-system repository
• ◻️ Copy markdown files to docs/ folder
• ◻️ Copy images to docs/images/ folder
• ◻️ Update config.json with site info
• ◻️ Update frontmatter in markdown files
• ◻️ Convert proprietary syntax to standard Markdown
• ◻️ Update internal links (remove .md,use relative paths)
• ◻️ Test build:npm run build
• ◻️ Test dev server:npm run dev
• ◻️ Check all pages render correctly
• ◻️ Check all images load
• ◻️ Test search functionality
• ◻️ Test dark mode
• ◻️ Test mobile responsiveness
• ◻️ Setup GitHub Actions for deployment
• ◻️ Deploy and verify live site

Need Help?#

If you encounter issues during migration:

1. Check the Troubleshooting Guide
2. Search GitHub Issues
3. Create a new issue with:
   • Source system name and version
   • Error messages
   • Sample problematic content

Migration Tools#

Consider these tools to help with migration:

Content Conversion:

• pandoc - Convert between markup formats
• remark - Markdown processor
• markdown-link-check - Verify links after migration

Automation:

# Example:Batch convert frontmatterfind docs -name "*.md" -exec sed -i 's/sidebar_position:/# sidebar_position:/g'{}\;# Example:Update image pathsfind docs -name "*.md" -exec sed -i 's|/img/|images/|g'{}\;# Example:Remove .md from linksfind docs -name "*.md" -exec sed -i 's/\(\[.*\]\(.*\)\.md\)/\1\)/g'{}\;

Validation:

# After migration,check for issuesnpm run build 2>&1 | grep -i "warning\|error"# Test all pages loadnpm run serve# Then visit http://localhost:3000