@sinch/readme-sync v1.1.20

Publish local Markdown content files to ReadMe

This is a CLI application that allows to offload the editing workflow of a documentation site published on ReadMe (previously known as "ReadMe.io") to a local repository of Markdown content files.

Main features:

• Fetch an existing documentation site from ReadMe using the API as a catalog of local Markdown content files
• Push a catalog of Markdown content files to ReadMe using the API
• Optionally clean up stale ReadMe pages (pages which do not have a corresponding Markdown content file) on push
• Perform sanity checks on the local Markdown catalog, such as finding broken links
• Convert ReadMe-proprietary widgets (such as images, tables, callouts, etc.) to a more generic Markdown equivalent
  • Optionally, download images hosted on ReadMe to the local repository and modify references
• Host locally specified static files (images and other documentation related files) on GitHub pages and refer to them on the ReadMe pages (see the hostedFiles filter described below)
• Add custom dynamic footer to pages. Footers are specified as Mustache templates.

Markdown content files

Directory structure

All content is expected to be stored in your project as Markdown (.md) files under the docs directory (the actual directory name can be configured). Each subdirectory within the main directory represents a category slug, and subsequent subdirectories mimic the page hierarchy in ReadMe.

Note: Although the tool will handle creating content pages, it cannot currently create content categories on your ReadMe documentation site. These must be created by hand via the ReadMe admin UI.

File format

The local Markdown content files act as the database of pages and their contents. To support "storing" more than the actual Markdown content, additional metadata about each page is specified in YAML front matter.

Full example:

---
title: Welcome
excerpt: This is the entry point of our documentation
hidden: 'true'
next:
  pages:
    - other-page-slug1
    - other-page-slug2
  description: Text to be shown in the What's Next box
---
# This is the page header

And some content underneath.

The following YAML attributes are supported:

Using the readme-sync CLI in your project

Installation

To install the CLI in your project, run:

$ npm install @sinch/readme-sync --save-dev

You can also install the CLI globally (which would be preferred for usability):

$ npm install -g @sinch/readme-sync

NOTE

If you install the CLI locally to your project (instead of globally), you'll need to run it with npx:

$ npx readme-sync [command] [options]

When you install it globally (-g npm option), you can run it directly:

$ readme-sync [command] [options]

API key

You will need the API key for your ReadMe account before using the CLI. It can be obtained via the ReadMe admin UI.

Configuration

Global configurations can be provided either :

• via -- global options on the command line
• via environment variables
• via a .env file to automatically set environment variables (recommended approach)

If both global options and environment variables are provided, the -- global option will have precedence over the environment variable.

The following configurations are available:

See the general help (./readme-sync -h) for details of each configuration option.

config.yml configuration file

In addition to the global configurations listed above, you can provide more general configurations that are not expected to change between command runs in a YAML file. By default, this file is expected to be named config.yml and be located in the current working directory. The name of the file can be configured using the --config CLI option.

The following fields can be provided in the YAML configuration file:

Content Filters

Content filters are transformations that can be applied to content pages before they are pushed to ReadMe. To ensure local content stays unchanged when that content gets fetched back from ReadMe, all filters must be able to rollback their changes on the way back.

hostedFiles filter

This filter is to be used when content files are hosted on a publicly-accessible Web server. All links specified as relative paths in the content pages will be converted to an equivalent public URL based on the filter's baseUrl configuration value. Paths are assumed to be specified as relative to the page in which the files are referenced.

Configuration attributes:

Example config.yml configuration

filters:
  - hostedFiles:
      baseUrl: https://GITHUB_USERNAME.github.io/REPO/

footer filter

Renders a Mustache template as the footer of all content files.

The Mustache template is rendered with a view object that includes the following attributes:

Configuration attributes:

Example config.yml configuration

filters:
  - footer:
      template: templates/footer.mustache
      someAttribute: Hello there!

Given the above configuration and the following Mustache template:

<span id="footer">{{someAttribute}}</span>

The following footer would be rendered on each content page:

<span id="footer">Hello there!</span>

Get help

You can get help for the CLI or for any command by running it with -h argument:

$ ./readme-sync [command] -h

Commands

push

Pushes local Markdown content files to ReadMe via their public API. It is assumed that each .md file in the contents directory matches the slug of the page in ReadMe.

Usage examples

Push contents for all categories defined in config.yml:

$ ./readme-sync push

Push contents for a specific category:

$ ./readme-sync push sms

Simulate (dry run) a push of only locally Git-staged files:

$ ./readme-sync push sms --staged-only --dry-run

Over ride the hidden parameter, great when you want to make pages visible on a temporary site while keeping them hidden in the main site

$ ./readme-sync push sms -h false

fetch

Fetches up-to-date contents from ReadMe via their public API in a local folder. This command will create or update local .md files that represent the current content in ReadMe, organized in directories that mimic the category/page hierarchy stored in ReadMe.

Usage examples

Fetch contents of all categories defined in config.yml:

$ ./readme-sync fetch

Fetch contents for a specific category:

$ ./readme-sync fetch sms

markdownize

Converts ReadMe-specific widget blocks to standard Markdown.

Usage examples

Replace all ReadMe widgets with their Markdown equivalent, in each and every page:

$ ./readme-sync markdownize

Only show what changes would be performed without actually persisting them:

$ ./readme-sync markdownize --dry-run

Only convert Code and Image widgets from a specific content file:

$ ./readme-sync markdownize --file sms/sms.md --widgets code,image

validate

Runs a few sanity checks on content files, such as checking for broken links (both internal / cross references and remote URL links). See command help (-h) for details on supported validators.

Usage examples

Run all validations on all content files:

$ ./readme-sync validate

Validate only cross references for a single file:

$ ./readme-sync markdownize --file sms/sms.md --validators xrefs

Contributing / Local development

If NVM (Node Version Manager) is not installed, install it.

Then, make sure the right Node version is installed and in use:

$ nvm install
$ nvm use

Finally, install project dependencies:

\$ npm install

To run tests, run

$ npm test

You should now be able to work on the project locally!

Releasing a new version

GitHub Actions are used to publish the package to NPM for release. The workflow is appropriately named Publish to NPM and is executed automatically whenever a GitHub Release is created.