Edit with AI

How to get there: Go to your Knowledge Base board → open the actions menu → click Edit with AI.

Edit your knowledge base using AI-powered coding tools like Claude Code or Cursor. Export your knowledge base as markdown files, let AI make the changes, then sync back.

Overview

The Edit with AI feature allows you to:

• Export & re-import - Download your knowledge base as a ZIP, edit with AI, upload to sync
• AI-powered editing - The export includes instruction files (CLAUDE.md and .cursorrules) so AI tools understand the structure
• Track changes - Only modified articles are updated
• Preserve links - Internal links between articles work automatically
• Upload images - Images are uploaded to S3 and linked in articles

AI-Assisted Workflow

This feature is designed to work with AI coding tools:

1. Export your knowledge base from the Edit with AI dialog
2. Unzip and open the folder in Claude Code, Cursor, or any AI-powered editor
3. The included instruction files (CLAUDE.md for Claude Code, .cursorrules for Cursor) give the AI all the context it needs
4. Ask the AI to create, edit, or reorganize your documentation
5. ZIP the folder and sync back to publish your changes

This workflow lets you leverage AI to write, update, and maintain your documentation at scale.

Folder Structure

Organize your markdown files in folders that match your knowledge base structure:

my-docs/
├── _index.md                 # Root section description (optional)
├── getting-started/
│   ├── _index.md             # Section description
│   ├── installation.md       # Article
│   └── quick-start.md        # Article
├── features/
│   ├── _index.md
│   ├── user-segments.md
│   └── advanced/             # Nested section
│       ├── _index.md
│       └── api-reference.md
└── images/
    ├── screenshot.png
    └── diagram.png

Folders = Sections

Each folder becomes a section (topic) in your knowledge base. Nested folders create nested sections.

_index.md = Section Description

Create a file named _index.md in a folder to set the section's title and description:

---
title: Getting Started
icon: rocket-takeoff
color: "#60a5fa"
---

Learn the basics and get up and running in minutes.

The frontmatter supports:

The body text (after frontmatter) becomes the section description. Keep it as plain text - markdown formatting is stripped.

.md Files = Articles

Any .md file (except _index.md) becomes an article. The filename determines the article's slug:

images/ Folder

Place images in an images folder (or img, assets, media). These are automatically uploaded to S3.

Writing Articles

Basic Format

Articles are standard markdown files. The first H1 heading becomes the article title and is removed from the body:

# Installation Guide

Follow these steps to install the application.

## Requirements

- Node.js 16+
- npm or yarn

## Steps

1. Clone the repository
2. Run `npm install`
3. Start with `npm start`

In this example, "Installation Guide" becomes the article title. The article body starts from "Follow these steps...".

Optional Frontmatter

You can add YAML frontmatter for additional control:

---
title: Custom Title Here
order: 1
---

Your content here...

When using frontmatter with a title, you don't need an H1 in the body.

Images

Relative Paths

Reference images using relative paths:

![Screenshot](../images/screenshot.png)

![Diagram](./images/diagram.png)

During sync, these are:

1. Uploaded to S3 (if new or changed)
2. Replaced with S3 URLs in the article

Image Change Detection

Images are only re-uploaded when their content changes. The system tracks a hash of each image to avoid unnecessary uploads.

Internal Links

Link between articles using relative markdown links:

See the [installation guide](/f/knowledgebase/installation) for setup instructions.

For advanced usage, check [API Reference](/f/knowledgebase/api-reference).

These are automatically converted to fixed URLs (/f/{board}/{slug}) that work in your knowledge base.

Fixed URLs

Every synced article gets a permanent URL in this format:

/f/{board-slug}/{article-slug}

For example:

• /f/docs/installation
• /f/docs/quick-start
• /f/help/api-reference

These URLs redirect to the actual article URL, so they work even if the article title changes.

Exporting Your Knowledge Base

You can export your existing knowledge base as a ZIP file in the correct markdown format:

1. Go to your Knowledge Base board → actions menu → Edit with AI
2. Click Export as ZIP in the dialog
3. A ZIP file downloads with all your sections and articles

The export includes:

• Folders for each section
• _index.md files with section title, icon, and color
• Article markdown files with title as H1
• CLAUDE.md - instruction file for Claude Code
• .cursorrules - instruction file for Cursor

You can also export directly from the actions menu via the Export button.

This is useful for:

• Editing your documentation with AI tools
• Backing up your documentation
• Migrating to a local editing workflow
• Starting with your existing content structure

How to Sync

Step 1: Create a ZIP File

Zip your documentation folder:

cd my-docs
zip -r ../my-docs.zip .

Or right-click the folder and choose "Compress" on macOS.

The ZIP can contain a root folder - it will be detected automatically.

Step 2: Open the Edit with AI Dialog

1. Go to your Knowledge Base board
2. Open the actions menu → click Edit with AI (admin only)

Step 3: Upload and Preview

1. Select your ZIP file
2. Click Preview Changes
3. Review what will be created, updated, or deleted

Step 4: Confirm Deletions

If articles exist in your knowledge base but not in your ZIP:

• They appear in the "Articles to Delete" section
• Check the ones you want to delete
• Unchecked articles are preserved

Step 5: Execute

Click Execute Sync to apply all changes. You'll see a log of everything that happened.

Matching Logic

How Articles Are Matched

Articles are matched by their slug (derived from filename):

If an article with the same slug exists, it's updated. Otherwise, a new article is created.

How Sections Are Matched

Sections are matched by their folder path slug:

Tips

Keep Slugs Stable

Don't rename files unless you want to create new articles. The old article will be marked for deletion.

Use Descriptive Filenames

Since filenames become slugs and appear in URLs, use descriptive, lowercase, hyphenated names:

• Good: user-authentication.md
• Bad: doc1.md

Preview Before Syncing

Always review the preview to avoid accidental deletions or duplicate content.

Organize with Folders

Use folders to create a logical hierarchy. Each folder becomes a navigable section in your knowledge base.

Troubleshooting

Images Not Showing

• Check that the image path is correct relative to the markdown file
• Ensure the image is included in the ZIP
• Check the sync log for warnings about missing images

Links Not Working

• Use relative paths (./other-article.md)
• Ensure the linked article exists in your ZIP
• Check that the filename spelling matches exactly

Article Not Updating

• The content hash is compared - if nothing changed, no update occurs
• Check that you saved the file before zipping
• Try making a small change to force an update

Wrong Section

• Check folder structure in your ZIP
• Verify the article is in the correct folder
• Section matching is based on folder path

Example Workflow

1. Initial Setup

   • Create a docs folder on your computer
   • Add your first articles as .md files
   • ZIP and sync to create the initial knowledge base

2. Daily Updates

   • Edit markdown files locally
   • Add new articles as needed
   • ZIP and sync - only changes are applied

3. Collaboration

   • Store docs in a Git repository
   • Team members can edit and commit
   • Sync from the latest version