GitHub Import

Cirth can import markdown documentation directly from your GitHub repositories, making it easy to migrate existing docs or keep documentation close to your code.

How It Works

1. Connect - Provide your repository details

2. Preview - Select which files to import

3. Import - Cirth converts markdown to pages

The import process:

• Parses frontmatter for metadata

• Extracts titles from H1 headings

• Converts markdown to rich HTML

• Generates SEO-friendly slugs

Starting an Import

1. Go to your Project Dashboard

2. Click Import from GitHub

3. Enter repository details:

   • Repository: owner/repo or full URL

   • Branch: Usually main or master

   • Docs Path: Folder containing docs (e.g., /docs)

Repository Format

Supported File Types

• .md - Standard markdown

• .mdx - Markdown with JSX (converted to standard markdown)

Recommended Structure

      

        plaintext
        
          
          
        
      
    your-repo/
├── docs/
│   ├── getting-started.md
│   ├── installation.md
│   ├── configuration.md
│   └── api/
│       ├── overview.md
│       ├── authentication.md
│       └── endpoints.md
└── README.md

Frontmatter Support

Add YAML frontmatter to control import behavior:

      

        markdown
        
          
          
        
      
    ---
title: Getting Started
description: Learn how to get started with our SDK
order: 1
---

# Getting Started

Your content here...

Supported Frontmatter Fields

Import Preview

Before importing, Cirth shows a preview:

• File path - Original location in repo

• Title - Extracted or from frontmatter

• Slug - Generated URL path

You can:

• Select/deselect individual files

• Select all or none

• Review titles before import

Slug Generation

Slugs are automatically generated from file paths:

Handling Conflicts

If a slug already exists:

• Existing page content is replaced

• Page settings are preserved

• History is maintained

To avoid conflicts:

• Use unique file names

• Check existing pages before import

Private Repositories

To import from private repositories:

1. Generate a GitHub Personal Access Token

2. Required scopes: repo (for private repos)

3. Enter token when prompted during import

Security Note: Tokens are used only during import and are not stored.

Import History

Track your imports:

1. Go to Project Settings > GitHub

2. View import history with:

   • Date and time

   • Repository and branch

   • Files imported

   • Status (success/failed)

Re-importing

To sync with repository changes:

1. Click Import from GitHub again

2. Your previous settings are remembered

3. Select files to re-import

4. Existing pages are updated

Best Practices

Organize Your Repository

      

        plaintext
        
          
          
        
      
    docs/
├── 01-getting-started/
│   ├── 01-introduction.md
│   ├── 02-installation.md
│   └── 03-quick-start.md
├── 02-guides/
│   ├── 01-basics.md
│   └── 02-advanced.md
└── 03-api-reference/
    └── 01-overview.md

Using numbered prefixes helps maintain order.

Use Frontmatter

Always include frontmatter for:

• Consistent titles

• SEO descriptions

• Explicit ordering

Keep README Separate

Your repo's README.md is often different from documentation. Consider:

• Excluding it from imports

• Or creating a dedicated docs/ folder

Regular Syncs

Set a schedule to re-import:

• After major releases

• When docs are updated in the repo

• As part of your release process

Troubleshooting

Files Not Showing

• Check the Docs Path is correct

• Ensure files have .md extension

• Verify branch name matches

Wrong Titles

• Add title to frontmatter

• Ensure H1 heading is at the top

• Check for special characters

Import Fails

• Check repository is accessible

• Verify branch exists

• For private repos, check token permissions