README Box

Lil' helper for replacing a section of the contents of a README.

Usage

Installation

$ npm install readme-box

const { ReadmeBox } = require('readme-box')
import { ReadmeBox } from 'readme-box'

You can quickly update a section of a README:

const result = await ReadmeBox.updateSection('New contents!', {
  owner: 'JasonEtco',
  repo: 'example',
  token: process.env.GITHUB_TOKEN,
  // branch is assumed to be 'master' by default, you can also specify `branch: 'main'`
  branch: 'main',
  section: 'example-section',
  // set to `true` to allow empty commits when there are no changes
  emptyCommits: false
})

// `result` is the response object of the README update request or
// `undefined` if no changes were made.

Or, if you need to access parts of it more granularly, you can use the ReadmeBox class methods:

const box = new ReadmeBox({ owner, repo, token })

// Get the contents of the README from the API
const { content, sha } = await box.getReadme()

// Get the contents of a section of the provided string
const sectionContents = box.getSection('example-section', content)

// Return a string with the replaced contents
const replacedContents = box.replaceSection({
  section: 'example-section',
  oldContent,
  newContent
})

// Update the README via the API, with an optional commit message
await box.updateReadme({ content, sha, message: 'Updating the README!' })

How it works

ReadmeBox.updateSection combines a couple of the methods exposed on the ReadmeBox class, to do the following:

• Get the README file's contents from the API
• Replace a section of it using Regular Expressions
• Update the file via the API

It expects your README to have a "section", using HTML comments:

Check out this README!

<!--START_SECTION:example-section-->
Old contents...
<!--END_SECTION:example-section-->

When the above example code is run, everything between the start and end comments will be replaced.

Local Development

This project was bootstrapped with TSDX. Below is a list of commands you will probably find useful.

npm start

Runs the project in development/watch mode. The project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab. The library will be rebuilt if you make edits.

npm run build

Bundles the package to the dist folder. The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module). s

npm test

Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit.