{"id":17164690,"url":"https://github.com/haroldtreen/readmeio-sync","last_synced_at":"2025-04-13T13:54:00.219Z","repository":{"id":57348757,"uuid":"37609942","full_name":"haroldtreen/readmeio-sync","owner":"haroldtreen","description":"↕️ A tool for syncing local markdown files to Readme.io","archived":false,"fork":false,"pushed_at":"2017-01-09T20:54:33.000Z","size":288,"stargazers_count":21,"open_issues_count":5,"forks_count":11,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-03-27T04:51:19.636Z","etag":null,"topics":["cli","javascript","node","readme","sync"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/haroldtreen.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}},"created_at":"2015-06-17T17:28:15.000Z","updated_at":"2023-07-10T01:08:31.000Z","dependencies_parsed_at":"2022-08-25T18:51:13.584Z","dependency_job_id":null,"html_url":"https://github.com/haroldtreen/readmeio-sync","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haroldtreen%2Freadmeio-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haroldtreen%2Freadmeio-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haroldtreen%2Freadmeio-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haroldtreen%2Freadmeio-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haroldtreen","download_url":"https://codeload.github.com/haroldtreen/readmeio-sync/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248322608,"owners_count":21084336,"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":["cli","javascript","node","readme","sync"],"created_at":"2024-10-14T22:52:32.874Z","updated_at":"2025-04-13T13:54:00.196Z","avatar_url":"https://github.com/haroldtreen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# readmeio-sync\nA tool for managing your `Readme.io` documentation locally.\n\n**NOTE** This project is not officially supported by ReadMe. For support, please use the [GitHub Issues](https://github.com/haroldtreen/readmeio-sync/issues) for this project.\n\n[![Code Climate](https://codeclimate.com/github/mobify/readmeio-sync/badges/gpa.svg)](https://codeclimate.com/github/mobify/readmeio-sync)\n[![Coverage Status](https://coveralls.io/repos/mobify/readmeio-sync/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/mobify/readmeio-sync?branch=master)\n[![npm version](https://badge.fury.io/js/readmeio-sync.svg)](https://badge.fury.io/js/readmeio-sync)\n\n## Usage\n\n### 1) Tool Setup:\n\n**For Regular Use:**\n```\nnpm install -g readmeio-sync\n```\n\n**For Development \u0026 Testing:**\n\n```\ngit clone git@github.com:mobify/readmeio-sync.git\ncd readmeio-sync\nnpm link\ncd ../\u003cyour_readmeio_project\u003e\nnpm link readmeio-sync\n```\n\n### 2) Credential Setup:\nThis tool logs into Readme.io for you in order to upload files. For this to work, it needs your credentials!\n\nThe `README_EMAIL` and `README_PASSWORD` environment variables need to be set for `readmeio-sync` to know your credentials.\n\n```bash\nexport README_EMAIL=\u003creadmeio_account_email\u003e\nexport README_PASSWORD=\u003creadmeio_account_password\u003e\n```\n\n### 3) Config Setup:\n`readmeio-sync` differentiates between your production/staging projects using the `syncConfig.json` file.\n\nYou can set the name of these projects using the `config` command.\n\n```\nreadmeio-sync config -s \u003cstaging-project-slug\u003e -p \u003cproduction-project-slug\u003e\n```\nThis will generate a `syncConfig.json` file with the proper keys set.\n\n### 4) Project Initialization:\nInitialization allows you to download all your existing content from Readme.io.\n\nIt also creates a new `syncPaths.json` file which represents the structure of your documentation and links to all your local content directories.\n\n```\nreadmeio-sync init\n```\n\nThis will use the `production` slug that you should have configured in step 3.\n\n### 5) Project Upload:\nUpload allows you to push updated content to Readme.io. This might include:\n\n* New categories, docs or custom pages.\n* Changes in content files.\n* Changes to document titles or excerpts.\n* Changes to the way you want to order content.\n* New Slugs\n* etc.\n\nOnce your project has been initialized and has a config, you can upload using the upload command.\n\n```\nreadmeio-sync upload [--production]\n```\nIncluding the production flag will push the content to production.\n\n### 6) Cleaning Readme.io:\nWhen you remove content files, it does not auto-magically delete it from your Readmeio project too. **Upload only does updates and creates.**\n\nIf you have out of date content on your Readmeio project, you can use the `clean-remote` command to remove all content that is not specified in your filesystem.\n\n```\nreadmeio-sync clean-remote [--production]\n```\n\nThis will look at the state of your project, compare it to the state of your documentation, and delete whatever is not specified locally. This will be done for staging unless the production flag is set.\n\nSometimes 'ghost' documents can appear in Readme. These are documents that have been created but are no longer shown in the list of documentation. Since you can't see them in the list of documentation, they can't be deleted.\n\nAdditionally, attempting to create a new document with the same slug as a ghost doc will cause a document with a numbered slug to be created instead (eg. getting-started -\u003e getting-started-1).\n\nTo make sure none of your docs have slugs associated to ghost documents, an `--aggressive` flag can be set.\n\nWhen this flag is set, `readmeio-sync` will clean documents that only exist in Readme AND docs that only exist locally (and perhaps haven't been uploaded due to slug naming conflicts).\n\n```\nreadmeio-sync clean-remote [--aggressive]\n```\n\n**Note**: If you remote clean a project and it removes all the documentation, Readmeio will not allow you to go into the documentation section. You will need to upload new content with the `readmeio-sync upload` command to get it working again.)*\n\n\n## Configuration\n\nFor an in-depth explanation of how to configuration works, see [CONFIGURATION.md](https://github.com/mobify/readmeio-sync/blob/master/CONFIGURATION.md)\n\n\n## [Known Issues](https://github.com/mobify/readmeio-sync/issues)\n\n1. Doing a remote-clean when you have no documentation in your `syncPaths.json` file will cause all your documentation on readme.io to be deleted (after all, you are saying \"delete all the things I don't have specified locally\"...which is nothing!). Having no documentation causes Readme.io to break (you can't enter the documentation section of the site). To fix this you will have to add a document to your `syncPaths.json` and upload it...or get in contact with Readme.io and admit you were using internal APIs (OOPS!).\n\n1. Custom pages are not versioned. Ideally they would be, and that's why the \"customPages\" section exists in each version of the `syncPaths.json`. When you initialize a project, the same custom pages will be downloaded for both versions and specified separately in the `syncPaths.json`. If you try and upload while the pages are specified in both versions, duplicates will be created. \u003cbr/\u003e\u003cbr/\u003e **You can fix this by:**\n\u003cbr /\u003e1. Deleting all the custom pages in all versions except one (however if you `clean-remote` with this configuration, all custom pages will be deleted and you'll have to upload again). \u003cbr/\u003e2. `clean-remote` after each upload.\n\n1. This tool is still in beta and may burn your project to the ground. Test it out, log issues, submit PRs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharoldtreen%2Freadmeio-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharoldtreen%2Freadmeio-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharoldtreen%2Freadmeio-sync/lists"}