{"id":19179750,"url":"https://github.com/holistics/readme-exporter","last_synced_at":"2025-04-14T23:26:03.692Z","repository":{"id":145841200,"uuid":"307115592","full_name":"holistics/readme-exporter","owner":"holistics","description":"Export Readme.com (readme.io) docs into Markdown (Docusaurus)","archived":false,"fork":false,"pushed_at":"2023-07-24T07:35:55.000Z","size":9963,"stargazers_count":6,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T11:21:27.102Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/holistics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2020-10-25T14:21:15.000Z","updated_at":"2025-03-16T13:26:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"e4f4fda8-d92d-4cc0-bbfa-b8f7ca6c8256","html_url":"https://github.com/holistics/readme-exporter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holistics%2Freadme-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holistics%2Freadme-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holistics%2Freadme-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holistics%2Freadme-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holistics","download_url":"https://codeload.github.com/holistics/readme-exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248976754,"owners_count":21192465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-11-09T10:44:32.181Z","updated_at":"2025-04-14T23:26:03.673Z","avatar_url":"https://github.com/holistics.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Export Readme.com to Markdown\n\nReadme.com is a SaaS tool to create docs site. This little script exports data from a readme.com (readme.io) documentation site into markdown files. It also downloads images from Readme.com into your computer.\n\n![](readme-exporter-f15.gif)\n\n\n## Why this script\n\n* We were using readme.com (previously readme.io) as a documentation site for a while, but outgrew it so we needed to migrate it to another tool.\n* We needed a way to quickly export data from Readme.com. Readme.com exposes [API interface](https://docs.readme.com/reference/intro-to-the-readme-api) for us to extract the data. However their exported\nMarkdown has a lot of custom blocks (e.g `[block:image]`). This script reads the API and convert readme.com custom blocks into\nnative markdown tags, and download the images along the way.       \n\n\n## Setting up\n\nThe script is written using Ruby. Make sure you have Ruby and bundler set up first. Then run bundle to install the gems:\n\n```bash\nbundle\n```\n\nMake a copy of `config.json` from `config.json.sample`\n\n```bash\ncp config.json.sample config.json\n```\n\nEdit config.json to include your readme.com API KEY and the images prefix.\n\n## Run the export\n\nFirst you need to extract list of slugs from the readme.com, and put them into runner.rb \n\n```ruby\nSLUGS = %w(\n  faqs\n  amazon-rds-setup\n  cohort-retention\n  amazon-aws-athena-setup\n  tunnel-setup\n  friendly-loading-messages\n  geo-heatmap\n  pie-chart-donut-chart\n  bubble-chart\n  connect-database\n  query-syntax\n  visualizations\n  introduction\n  embedded-analytics\n)\n```\n\nThen simply run:\n\n```bash\n./runner.rb\n```\n\nThe files will be generated:\n* `gen_docs_raw`: Raw readme.com markdown files \n* `gen_docs_final`: Parsed markdown files \n* `gen_images`: Images downloaded from readme.com \n\n\n## FAQs\n\n### Does this work for any markdown-based documentations?\n\nWe wrote this to work with [Docusaurus](https://v2.docusaurus.io/). But it should work with any markdown-based sites you\nchoose (Jekyll, Middleman, etc) since it's just markdown.\n\n### How do I get a list of slugs?\n\nYou have to collect it manually for now (go to your readme.com docs and extract them down). We used a workaround by logging to Google Analytics and extract all the pageviews and get the URL list from there. As readme.com doesn't expose that API, a future work will be to write a function to iterate and build the list manually.\n\n\n### What is the image_path_prefix for?\n\nWhat is the image prefix for? It's used to replace this block of code into this:\n\nIt's used to replace this markdown block of readme.com\n\n```\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/ea963a2-add_user.png\",\n        \"add_user.png\",\n        1465,\n        620,\n        \"#fbfbfc\"\n      ]\n    }\n  ]\n}\n[/block]\n```\n\nto\n\n```\n![](https://mycdn.com/images/ea963a2-add_user.png)\n```\n\nHere, `https://mycdn.com/images/` is the prefix.\n\n## Development\n\nTests are written using Rspec. To run, simply run `rspec`\n\n\n## TODO\n\n- [x] Export pages into markdown\n- [x] Download images from readme.com\n- [ ] Command to automatically get list of pages + navigation structure\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholistics%2Freadme-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholistics%2Freadme-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholistics%2Freadme-exporter/lists"}