{"id":47874482,"url":"https://github.com/knu/chatgpt2obsidian","last_synced_at":"2026-04-19T15:09:55.944Z","repository":{"id":301878404,"uuid":"1006485939","full_name":"knu/chatgpt2obsidian","owner":"knu","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-18T13:52:11.000Z","size":2414,"stargazers_count":5,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T15:34:47.839Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"knu"}},"created_at":"2025-06-22T11:35:12.000Z","updated_at":"2026-04-18T13:52:16.000Z","dependencies_parsed_at":"2025-08-02T17:08:17.742Z","dependency_job_id":"419612f6-90a1-4f15-97fc-edd85d9edb4d","html_url":"https://github.com/knu/chatgpt2obsidian","commit_stats":null,"previous_names":["knu/chatgpt2obsidian"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/knu/chatgpt2obsidian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knu%2Fchatgpt2obsidian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knu%2Fchatgpt2obsidian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knu%2Fchatgpt2obsidian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knu%2Fchatgpt2obsidian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knu","download_url":"https://codeload.github.com/knu/chatgpt2obsidian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knu%2Fchatgpt2obsidian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32011029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T01:08:37.206Z","updated_at":"2026-04-19T15:09:55.933Z","avatar_url":"https://github.com/knu.png","language":"Ruby","funding_links":["https://github.com/sponsors/knu"],"categories":[],"sub_categories":[],"readme":"# ChatGPT to Obsidian Converter\n\nThis tool converts ChatGPT export data into Obsidian Flavored Markdown files with proper frontmatter metadata and formatting.\n\n## Features\n\n- **Obsidian integration**: Generates files with YAML frontmatter and Obsidian syntax like [Callouts](https://help.obsidian.md/callouts)\n- **Attachment handling**: Copies and links image attachments with proper file organization\n- **Map support**: Exports map search results into official Obsidian Bases Map views backed by generated location notes\n- **Conversation structure**: Preserves the hierarchical structure of ChatGPT conversations\n- **Duplicate prevention**: Handles filename conflicts and tracks existing files\n- **Rich content support**: Processes web search results, thoughts, code blocks, app-pairing contexts, and multimedia content\n\n## Usage\n\n### Docker (Recommended)\n\nThe easiest way to use this tool is with Docker - no installation required!\n\n```sh\n# Basic usage with ZIP file\ndocker run --rm -v /path/to/chatgpt-export:/input -v /path/to/vault/subdirectory:/output akinori/chatgpt2obsidian /input/chatgpt-export.zip /output\n\n# Basic usage with extracted directory\ndocker run --rm -v /path/to/chatgpt-export:/input -v /path/to/vault/subdirectory:/output akinori/chatgpt2obsidian /input /output\n\n# With custom attachments subdirectory\ndocker run --rm -v /path/to/chatgpt-export:/input -v /path/to/vault/subdirectory:/output akinori/chatgpt2obsidian --attachments-subdirectory images /input/chatgpt-export.zip /output\n\n# With custom maps subdirectory\ndocker run --rm -v /path/to/chatgpt-export:/input -v /path/to/vault/subdirectory:/output akinori/chatgpt2obsidian --maps-subdirectory geo /input/chatgpt-export.zip /output\n```\n\n### Command-line Parameters\n\n- `\u003cinput_path\u003e`: ChatGPT export zip file or its extracted directory\n- `\u003coutput_directory\u003e`: Directory where converted Markdown files will be saved\n\n### Options\n\n- `-a, --attachments-subdirectory NAME`: Specify custom attachments subdirectory name (default: \"attachments\")\n- `--maps-subdirectory NAME`: Specify custom maps subdirectory name (default: \"maps\")\n- `-c, --created-key KEY`: Specify the frontmatter key for created timestamp (default: \"created\")\n- `-u, --updated-key KEY`: Specify the frontmatter key for updated timestamp (default: \"updated\")\n- `-j, --json-output DIR`: Output raw conversation JSON files in addition to Markdown\n- `-v, --verbose`: Enable verbose debug output\n- `-h, --help`: Show help message\n\n### Alternative: Local Ruby Installation\n\nIf you prefer to run the script directly:\n\n#### Requirements\n- Ruby 3.4 or later\n\n#### Installation\n```sh\ngit clone https://github.com/knu/chatgpt2obsidian.git\ncd chatgpt2obsidian\n```\n\n#### Usage\n```sh\n# Basic usage with ZIP file\n./chatgpt2obsidian chatgpt-export.zip /path/to/vault/subdirectory\n\n# Basic usage with extracted directory\n./chatgpt2obsidian /path/to/extracted/chatgpt-export /path/to/vault/subdirectory\n\n# With custom attachments subdirectory\n./chatgpt2obsidian --attachments-subdirectory images chatgpt-export.zip /path/to/vault/subdirectory\n\n# With custom maps subdirectory\n./chatgpt2obsidian --maps-subdirectory geo chatgpt-export.zip /path/to/vault/subdirectory\n```\n\n## ChatGPT Export Process\n\n1. Go to ChatGPT Settings → Data Controls → Export Data\n2. Download your data when ready\n3. Use the path to the downloaded ZIP file or extract it and use the path to the extracted directory as the first argument\n\n```\n/path/to/chatgpt-export\n├── chat.html\n├── conversations-000.json\n├── conversations-001.json\n├── file-id-1-image-1.png\n├── file-id-2-image-2.jpg\n├── ...\n├── message_feedback.json\n├── shared_conversations.json\n└── user.json\n```\n\n## Output Structure\n\nThe script generates one Markdown file per conversation from the ChatGPT export data, along with any attachments (images, files) referenced in the conversations.\nIf a conversation contains map search results, it also generates location notes in a separate maps subdirectory and embeds an official Obsidian Bases Map view in the conversation note.  Rendering those embeds requires the official Obsidian Maps plugin.\nThe output is structured to be compatible with Obsidian's note-taking system, allowing for easy organization and retrieval of conversations.\nEach Markdown file is named after the conversation title, sanitized for filesystem compatibility, and includes all relevant metadata.\n\n```\n/path/to/vault/subdirectory/\n├── conversation_title_1.md\n├── conversation_title_2.md\n├── attachments/\n│   ├── file-id-1-image-1.png\n│   └── file-id-2-image-2.jpg\n├── maps/\n│   └── conversation_title_1/\n│       ├── map-12345678/\n│       │   ├── 01 Place A.md\n│       │   └── 02 Place B.md\n│       └── map-90abcdef/\n│           └── 01 Place C.md\n└── ...\n```\n\n### Markdown Format\n\nEach conversation file includes:\n\n- **YAML frontmatter** with metadata (title, dates, conversation ID, URL)\n- **Proper formatting** for user and assistant messages\n- **Obsidian callouts** for search results, thoughts, code blocks, app-pairing contexts, and multimedia content\n- **Linked attachments** with automatic file copying\n- **Map embeds** using official Obsidian Bases Map views when ChatGPT responses include location search results\n\nExample output:\n\n### Visual Comparison: ChatGPT vs Obsidian\n\nHere's how the same conversation appears in ChatGPT versus the converted Obsidian format:\n\n#### ChatGPT - Thoughts with Web Search\n![ChatGPT Thoughts](chatgpt-thoughts.png)\n\n#### Obsidian - Converted Thoughts Block\n![Obsidian Thoughts](obsidian-thoughts.png)\n\n#### ChatGPT - Main Content\n![ChatGPT Contents](chatgpt-contents.png)\n\n#### Obsidian - Converted Content\n![Obsidian Contents](obsidian-contents.png)\n\n#### Obsidian - File Header with Metadata\n![Obsidian Header](obsidian-header.png)\n\nThe conversion preserves all the rich content from ChatGPT while making it fully compatible with Obsidian's note-taking system.\n\n### Sample Markdown Output\n\n````markdown\n---\ntitle: How to learn Ruby programming\ncreated: 2025-07-05T19:31:55+09:00\nupdated: 2025-07-05T20:08:56+09:00\nconversation_id: 6868ff1b-0f5c-8007-8c50-b9faa489d84f\nconversation_url: https://chat.openai.com/c/6868ff1b-0f5c-8007-8c50-b9faa489d84f\nmodels:\n- o3\n---\n# User\nHow do I get started with Ruby programming?\n\n# ChatGPT\n\n\u003e [!abstract]- Thoughts\n\u003e The user asks, \"How do I get started with Ruby programming?\" This seems like a straightforward question, but...\n\u003e\n\u003e \u003e [!info]- Web Search: [latest stable release of Ruby programming language July 2025]\n\u003e \u003e\n\u003e \u003e \u003e [!abstract]- Search Results: [www.ruby-lang.org] [endoflife.date] [en.wikipedia.org] [www.jruby.org]\n\u003e \u003e \u003e \u003e [!info] www.ruby-lang.org\n\u003e \u003e \u003e \u003e - [Ruby Releases](https://www.ruby-lang.org/en/downloads/releases/ \"Ruby releases by version number ; Ruby 3.4.4, 2025-05-14, download ; Ruby 3.5.0-preview1, 2025-04-18, download...\")\n\u003e \u003e \u003e \u003e - [Ruby Programming Language](https://www.ruby-lang.org/en/ \"Ruby 3.5.0 preview1 Released. We are pleased to announce the release of Ruby 3.5.0-preview1...\")\n\u003e\n\u003e \u003e [!info]- Thought for 14 seconds\n\n\u003e [!tip] o3\n\nBelow is a compact, opinionated roadmap that will take you from \"I've never touched Ruby\" to \"I can ship something useful and idiomatic.\"\n\n### 1  Install Ruby the *right* way (≈ 20 min)\n\n| OS | Good default | Why |\n|----|--------------|-----|\n| macOS / Linux | **rbenv + ruby-build** | Lightweight, one‐command upgrades, plays nicely with system packages |\n| Windows | **RubyInstaller** or **WSL + rbenv** | Native or Unix-like, whichever feels less friction |\n| Anywhere | **asdf-vm** | One manager for many languages (nice if you already juggle Node, Go, etc.) |\n\n\u003e **Tip:** Install the latest stable (today that's 3.4.4) rather than the bleeding-edge preview (3.5.0-preview1) unless you *enjoy* rehearsing release notes.\n\nAfter installation:\n\n```bash\nruby -v         # sanity-check\ngem update --system\n```\n\n### 2  Open a REPL and poke around (≈ 15 min)\n\n```bash\nirb             # ships with Ruby\n```\n\nType `2.times { puts 'Hello, Ruby' }` and press ↩.\nWhen curiosity outgrows IRB, install **pry** for a richer console:\n\n```bash\ngem install pry\npry\n```\n````\n\n## Content Type Support\n\nThe script handles various ChatGPT content types:\n\n- **Text messages**: Standard user and assistant conversations\n- **Source links**: Proper reference links embedded in response messages\n- **Thoughts**: Internal reasoning including chains of thought displayed in expandable blocks\n- **Web search results**: Included within Thoughts blocks\n- **Images**: Automatically copied and embedded\n- **Maps**: Exported as generated location notes plus embedded Obsidian Bases Map views\n- **Code execution**: Search queries and reasoning recaps\n- **Model information**: Shows the model name for each ChatGPT response and includes all model names in frontmatter\n- **Message filtering**: Filters out edited conversation branches using timestamp-based selection\n\n## File Naming\n\n- Conversation titles are sanitized for filesystem compatibility.\n- Special characters are replaced with underscores.\n- Duplicate titles get numbered suffixes (`_1`, `_2`, etc.).\n- Existing files are preserved and updated in place.\n- The original title is stored in frontmatter with the `title` key.\n  Obsidian community plugins like [Front Matter Title](https://github.com/snezhig/obsidian-front-matter-title) can make use of it.\n\n## Limitations\n\n- Not all content types in export files may be supported.\n- Unescaped special characters such as angle brackets or dollar signs can sometimes be misinterpreted by Obsidian as HTML tags or MathJax expressions.  While automatic escaping is theoretically possible, implementing it reliably is technically complex due to the nuances of the Markdown spec and Obsidian’s own extensions.\n\n## License\n\nCopyright (c) 2025-2026 Akinori Musha.\n\nLicensed under the 2-clause BSD license.  See `LICENSE` for details.\n\nVisit [GitHub Repository](https://github.com/knu/chatgpt2obsidian) for the latest information.\n\nPlease feel free to submit issues, feature requests, or pull requests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknu%2Fchatgpt2obsidian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknu%2Fchatgpt2obsidian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknu%2Fchatgpt2obsidian/lists"}