Markdown export

ko-markdown-export is a small, standalone Python script that pulls the live articles and categories from a KnowledgeOwl knowledge base and writes them out as a folder of Markdown (.md) files, organized by category. You can then upload that folder to Claude Projects, ChatGPT, or any tool that accepts Markdown files as a knowledge source.

The script and full setup instructions live on GitHub: github.com/silly-moose/ko-markdown-export. This article gives you an overview and walks through the KnowledgeOwl-specific pieces you'll need to run it.

What the ko-markdown-export script does

The ko-markdown-export script:

• Exports all of your live articles (those that are Published or marked Needs Review) as one Markdown file each.
• Mirrors your category hierarchy as folders, adding an _index.md for any category that has its own content, such as a description or a Topic Display or Custom Content body.
• Converts each article's HTML to Markdown and adds frontmatter to the top of every file: title, category path, created and modified dates, meta description, article ID, and a link back to the live article when you provide your knowledge base URL.
• Downloads any referenced images into a local images/ folder and links to them.
• Is re-runnable: each run clears and rewrites the output folder, so you always get a clean snapshot.

When you'd use it

You'd use this script in these situations:

• To give an AI tool a copy of your knowledge base as a knowledge source. For example, upload the exported folder to a Claude Project or a custom GPT so it can answer questions from your docs.
• To keep a portable, plain-text snapshot of your content that's easy to search, store, or track in version control.
• To reuse your content in any other tool that reads Markdown.

What you need

To run the script, you'll need:

• Python 3.9 or newer
• A terminal (Terminal on Mac, PowerShell on Windows)
• A KnowledgeOwl API key with Read permissions for Article, Category, and File. To create one, go to Account > API. For step-by-step instructions, refer to API keys.
• Your knowledge base ID (called the project_id in the API). To find it, refer to Find your knowledge base ID or project ID.

Set it up and run it

To set up the script and run it:

1. Download or clone the repository from GitHub and save it to a folder on your computer.
2. Open a terminal in that folder and install the dependencies:

   python3 -m pip install -r requirements.txt

3. Copy .env.example to .env. Open .env and make these edits:
   1. Add your API key to KO_API_KEY.
   2. Add your knowledge base ID to KO_PROJECT_ID.
   3. Optional: Add your knowledge base URL to KO_KB_URL to include a link back to each live article in the frontmatter.
   4. Optional: Change where the files are written by editing the KO_OUTPUT_DIR path.
4. Run the export:

   python3 export.py

The script writes your Markdown files, organized by category, into an output folder (export by default). For the full step-by-step, including how to upload the result to Claude or ChatGPT, refer to the repository README.

Good to know

• The export is a static snapshot. Re-run the script whenever you want to refresh it.
• The script exports articles and categories only. It doesn't include snippets, glossary terms, tags, or readers.
• Only live articles are exported. Draft, rejected, archived, and deleted articles are skipped.
• Links between your articles stay as KnowledgeOwl URLs, so they remain clickable in the exported files.
• Images that can't be downloaded, such as those behind a sign-in, keep their original URL as a link, and the script notes them in the terminal.