# readme-sync

> This is a CLI tool that synchronizes markdown files from a local directory (typically in a git repo) to https://readme.com.

Latest version **0.0.24** (published 2023-03-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install readme-sync
pnpm add readme-sync
yarn add readme-sync
bun add readme-sync
```

Provides the command `readme-sync`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.24 |
| Published | 2023-03-09 |
| First published | 2019-12-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 34 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Ben Iofel |
| Maintainers | ben-flow-io, flowtech |

## Links

- npm: https://www.npmjs.com/package/readme-sync
- Repository: https://github.com/flowcommerce/readme-sync
- Homepage: https://github.com/flowcommerce/readme-sync#readme
- Issues: https://github.com/flowcommerce/readme-sync/issues
- npm.io page: https://npm.io/package/readme-sync

## Dependencies (5)

- [chalk](https://npm.io/package/chalk.md) ^3.0.0
- [debug](https://npm.io/package/debug.md) ^4.1.1
- [yargs](https://npm.io/package/yargs.md) ^15.0.2
- [gray-matter](https://npm.io/package/gray-matter.md) ^4.0.2
- [isomorphic-fetch](https://npm.io/package/isomorphic-fetch.md) ^3.0.0

## Recent versions

- 0.0.24 (latest) — 2023-03-09
- 0.0.23 — 2021-01-11
- 0.0.22 — 2021-01-11
- 0.0.20 — 2020-10-26
- 0.0.19 — 2020-10-06
- 0.0.18 — 2020-06-30
- 0.0.17 — 2020-06-29
- 0.0.16 — 2020-06-11
- 0.0.15 — 2020-01-30
- 0.0.14 — 2020-01-30
- 0.0.13 — 2020-01-30
- 0.0.12 — 2020-01-30
- 0.0.11 — 2020-01-30
- 0.0.10 — 2020-01-30
- 0.0.9 — 2020-01-22
- … 7 more at https://npm.io/package/readme-sync/versions

## 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 <key> --version <version> --docs <dir>`

or, to just validate the files:

`npx readme-sync --apiKey <key> --version <version> --docs <dir> --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
    └── Configuration
        ├── index.md
        ├── 00 - Database.md
        └── 10 - Proxy.md
```

Becomes

![](result.png)

## 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 '<your_readme_api_key>': -H 'x-readme-version: <your_docs_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 <key> --version <version> --docs <dir>`

---
_Source: https://npm.io/package/readme-sync · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._