https://github.com/flowcommerce/readme-sync
Sync markdown files to readme.com
https://github.com/flowcommerce/readme-sync
cli docs markdown readme sync
Last synced: about 2 months ago
JSON representation
Sync markdown files to readme.com
- Host: GitHub
- URL: https://github.com/flowcommerce/readme-sync
- Owner: flowcommerce
- License: mit
- Created: 2019-12-24T00:00:11.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-12-09T17:52:19.000Z (over 1 year ago)
- Last Synced: 2025-08-30T12:47:18.295Z (9 months ago)
- Topics: cli, docs, markdown, readme, sync
- Language: TypeScript
- Homepage:
- Size: 261 KB
- Stars: 12
- Watchers: 9
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# readme.com Sync Tool
This is a CLI tool that synchronizes markdown files from a local directory (typically in a git repo) to https://readme.com.
## Usage
`npx readme-sync --apiKey --version --docs `
or, to just validate the files:
`npx readme-sync --apiKey --version --docs --validateOnly`
## Expected Directory Structure
Top level folders are mapped to categories. Second and third level `.md` files are synced as docs. Readme only supports two levels of nesting (Category > Parent Doc > Child Doc). If you want a doc with children, create a folder with the doc name, and create an `index.md` file inside it.
The folder and file names are turned into the slugs.
Example:
```
docs
├── Welcome
│ ├── 00-introduction.md
│ └── 10-license.md
└── Integration
├── 00-installation.md
├── 10-setup.md
└── 20-configuration
├── index.md
├── 00-database.md
└── 10-proxy.md
```
Becomes
## File Contents
Markdown, with front matter:
```markdown
---
title: "Installation"
excerpt: "How to Install Arch Linux" # optional
hidden: true # optional
---
# Installation
...
```
## Limitations
- Categories cannot yet be created automatically. They must be manually created in Readme. You can fetch the existing category slugs with
```bash
curl 'https://dash.readme.io/api/v1/categories?perPage=100' -u '': -H 'x-readme-version: '
```
Note that category slugs may differ from the category titles you see on dash.readme.io, so this API call is a good way to troubleshoot the error message "can't create categories."
## Syncing Behavior
- If you have a category on readme.com that you don't have locally, the category and its contents will remain untouched on readme.com.
- If you have a doc on readme.com that you don't have locally (but you have the category), it will be deleted from readme.com.
- If you have a doc locally that is not on readme.com, it will be uploaded to readme.com
- If you try to create two docs with the same name, you'll get an error about document slugs not being unique, even if the files are in separate categories.
- The publishing order is alphanumeric. You can force ordering by prefixing your files with `01-`, `02-`, etc. Then, these ordered pages go first in the table of contents (stripped of their `01-`, `02-` ordering prefixes).
## Development
1. `git clone https://github.com/flowcommerce/readme-sync`
1. `nvm install`
1. `npm install`
1. `npx ts-node sync/index.ts --apiKey --version --docs `
## Releasing a new version
```bash
$ npm version patch
$ npm publish
```