Migrating KB Articles from MkDocs

This guide provides specific instructions for efficiently converting existing MkDocs knowledge base articles to the OVI General Contracting Docusaurus platform.

Migration Quick Reference

MkDocs Feature	Docusaurus Equivalent	Migration Action
YAML frontmatter	YAML frontmatter	Update required fields
!!!note admonitions	:::note admonitions	Replace !!! with :::
mkdocs.yml navigation	sidebars.js	Map to new structure
docs/ folder structure	docs/ with categories	Reorganize files
MkDocs extensions	MDX components	Convert to Docusaurus equivalents

Migration Workflow

1. Analyze the Original MkDocs Article

Before conversion, examine these key elements of the MkDocs article:

• Frontmatter and metadata
• Content structure and heading hierarchy
• Special formatting (admonitions, code blocks, tables)
• Images and link references
• Any MkDocs-specific extensions or plugins used

2. Create Appropriate Docusaurus Frontmatter

MkDocs frontmatter often has different fields than what Docusaurus requires:

# Original MkDocs frontmatter example
---
title: Article Title
summary: Brief description
authors:
  - author1
date: 2023-01-01
---

Convert to Docusaurus frontmatter:

---
title: Article Title
description: Brief description
slug: article-title
sidebar_position: 3
tags:
  - relevant
  - tags
  - here
---

Required Frontmatter Fields for Docusaurus

• title: Preserve the original title
• description: Use the MkDocs summary/description if available
• sidebar_position: Determine appropriate position based on content hierarchy
• tags: Add relevant tags based on the content

File Placement

Determine the appropriate category based on the content type:

• Technical Reference - Technical guides, software instructions
• Procedure - Step-by-step work processes
• Process - Explanation of workflows
• Policy - Company policies and standards
• Specifications - Standards for artifacts
• Operating Model - Organizational structure
• KPI - Performance metrics
• Employees - Employee-specific information

3. Convert MkDocs-Specific Syntax

Admonitions

MkDocs uses !!! for admonitions while Docusaurus uses ::::

<!-- MkDocs -->
!!! note "Title"
    This is a note in MkDocs.
    The content is indented.

<!-- Docusaurus -->
:::note[Title]
This is a note in Docusaurus.
The content is NOT indented.
:::

Admonition Types Mapping

MkDocs	Docusaurus
!!! note	:::note
!!! tip	:::tip
!!! info	:::info
!!! warning	:::caution
!!! danger	:::danger
!!! success	:::success

Tabs

Convert MkDocs tabs to Docusaurus MDX tabs:

<!-- MkDocs -->
=== "Tab 1"
    Tab 1 content
=== "Tab 2"
    Tab 2 content

<!-- Docusaurus -->
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="tab1" label="Tab 1" default>
    Tab 1 content
  </TabItem>
  <TabItem value="tab2" label="Tab 2">
    Tab 2 content
  </TabItem>
</Tabs>

Code Blocks

Code blocks generally work the same way, but verify syntax highlighting:

<!-- Both use similar syntax -->
```python
def function():
    return True

4. Update Images and Links

Image Path Migration

1. Identify all image references in the MkDocs document
2. Determine proper storage location in Docusaurus:
   • For standard images: static/img/category-name/image-name.png
   • Keep Amazon-hosted images with original URLs

<!-- MkDocs image reference -->
![Alt text](../assets/images/screenshot.png)

<!-- Docusaurus equivalent -->
![Alt text](/img/category-name/screenshot.png)

Link Updates

1. Update internal document links to reflect the new Docusaurus structure
2. Use relative paths for internal links:

<!-- MkDocs -->
[Link text](../other-section/document.md)

<!-- Docusaurus -->
[Link text](../category/document)

Note that Docusaurus internal links don't require the .md extension.

5. Handle MkDocs Extensions

Convert any MkDocs-specific extensions to their Docusaurus equivalents:

MermaidJS

<!-- Both use similar syntax but might need import in Docusaurus -->
```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[End]
    B -->|No| D[Process]
    D --> A

#### MkDocs Material Icons
Convert Material icons to equivalent React icons or Unicode symbols.

```markdown
<!-- MkDocs Material -->
:material-information: Info text

<!-- Docusaurus equivalent (use appropriate import) -->
<InfoIcon /> Info text

6. Update Tables

Tables generally work the same way, but check formatting:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

7. Check for MkDocs-Specific Features

Look for and convert these MkDocs-specific features:

• Table of contents placement and settings
• Footnotes and annotations
• Custom blocks or containers
• Site variables and template substitutions

Common Migration Issues and Solutions

Problem: Admonition Content Not Displaying

Solution: Remove indentation from content inside Docusaurus admonitions.

Problem: Broken Internal Links

Solution: Update all internal links to use relative paths without the .md extension.

Problem: Images Not Displaying

Solution: Update image paths to match Docusaurus structure and ensure images are copied to the correct static folder.

Problem: Missing Frontmatter Fields

Solution: Ensure all required Docusaurus frontmatter fields are present (title, description, slug, sidebar_position).

Docusaurus-Specific Enhancements

Once basic migration is complete, consider these Docusaurus-specific enhancements:

Interactive Components with MDX

Enhance your documentation with React components:

import BrowserWindow from '@site/src/components/BrowserWindow';

<BrowserWindow url="https://example.com">
  <h2>Example content</h2>
  <p>This appears inside a browser window UI.</p>
</BrowserWindow>

Tabs for Alternative Methods

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="windows" label="Windows" default>
    Windows-specific instructions...
  </TabItem>
  <TabItem value="mac" label="Mac">
    Mac-specific instructions...
  </TabItem>
</Tabs>

Migration Checklist

Before considering a migration complete, verify these items:

• Frontmatter is updated to Docusaurus format with all required fields
• Admonitions are converted from !!! to ::: syntax
• Indentation is removed from admonition content
• All internal links are updated to relative paths without .md extension
• Image paths are updated and images are copied to the correct location
• MkDocs-specific features are converted to Docusaurus equivalents
• Heading hierarchy is preserved and properly formatted
• Code blocks have appropriate language tags
• Tables are properly formatted
• The document is placed in the appropriate category folder
• The sidebar configuration is updated if necessary

Batch Migration Tips

When migrating multiple MkDocs articles to Docusaurus:

1. Create a mapping document that tracks:

   • Original MkDocs file location
   • New Docusaurus file location
   • Migration status
   • Issues requiring follow-up

2. Use automated tools when possible:

   • Simple find and replace for admonition syntax (!!! to :::)
   • Regular expressions for more complex patterns
   • Scripts for frontmatter conversion and file organization

3. Migrate by category rather than one-off files:

   • Complete one content category before moving to the next
   • Ensures consistent navigation and cross-linking

4. Verify cross-references after migration:

   • Check and update links between documents
   • Ensure navigation paths are valid in the new structure

Testing the Migrated Content

After migration, verify the content works correctly in Docusaurus:

1. Run the development server:

   npm run start

2. Check the following:

   • Page loads without errors
   • Content displays as expected
   • Images appear correctly
   • Links work properly
   • Admonitions and special formatting render correctly
   • Navigation and sidebar display the page in the correct location

Automated Migration Script Example

For large-scale migrations, consider using a script like the following (pseudocode):

def migrate_mkdocs_to_docusaurus(mkdocs_file, docusaurus_output_path):
    # Read MkDocs file
    content = read_file(mkdocs_file)
    
    # Extract and convert frontmatter
    frontmatter = extract_frontmatter(content)
    docusaurus_frontmatter = convert_frontmatter(frontmatter)
    
    # Convert admonitions
    content = content.replace("!!!", ":::")
    content = remove_admonition_indentation(content)
    
    # Update internal links
    content = update_internal_links(content)
    
    # Update image paths
    content = update_image_paths(content)
    
    # Convert MkDocs-specific extensions
    content = convert_mkdocs_extensions(content)
    
    # Write to Docusaurus file
    write_file(docusaurus_output_path, docusaurus_frontmatter + content)

Questions and Support

If you encounter issues during the migration process, contact the documentation team for assistance. We're here to help ensure a smooth transition from MkDocs to Docusaurus for all knowledge base articles.