Skip to content

README.md

Latest commit

 

History

History
150 lines (88 loc) · 5.93 KB

README.md

File metadata and controls

150 lines (88 loc) · 5.93 KB

English | 中文

Kup

Kup logo

A CLI tool to sync local Markdown files to GitHub issues.

这款命令行工具可以把本地的 Markdown 文件同步到 GitHub issue。

Who Is It For

  • Bloggers who publish with GitHub issues and want to edit drafts locally, then publish new posts or update existing ones at any time.
  • Open-source authors who publish documentation through GitHub issues and want to sync docs from the repository to specific issues.
  • Anyone else who needs to update GitHub issues frequently.

Installation

Install it globally so you can call it from the command line at any time:

npm install -g kup-cli

(When a new version of Kup is released, run the same command again to upgrade.)

Usage

Publish a New Issue

kup ./path/to/file.md --repo foo/bar

Kup will publish the content of file.md as a new issue in the foo/bar repository, and report the new issue number after it succeeds.

Update an Existing Issue

kup ./path/to/file.md --repo foo/bar --id 123

Kup will update issue 123 in the foo/bar repository with the content of file.md.

Preparation

Updating GitHub issues requires authentication, so you need to provide a GitHub token for Kup to call the GitHub API.

  1. Create a new token on GitHub's "Personal access tokens" page, and make sure the repo scope is selected. (See this document for details.)

  2. Put the token into an environment variable:

    export GITHUB_TOKEN=ghp_**********

If Kup cannot read a token from the environment, it will prompt you for one in the terminal.

Command-Line Options

Option Short Value Type Description Notes
--repo -r string Specify the GitHub repository
--id -i integer Specify the issue number
  • Providing a number means updating an existing issue
  • Omitting it means publishing a new issue
--version -v - Show the version number
--help -h - Show help information

Advanced

How can I specify the repo option more conveniently?

Kup can determine the repo option in the following order of priority:

  1. The --repo option passed on the command line.
  2. The repo field in the Markdown file's metadata.
  3. The kup.repo field in the current project's package.json. Kup starts from the Markdown file's directory and searches upward for a package.json file.
  4. If kup.repo is not present in package.json, Kup will try to infer the repository name from the repository field and ask for confirmation before using it.
  5. If that still fails, Kup will continue searching for .git/config in the current or parent directories, then try to infer the repository name from the url field of remote "origin" and ask for confirmation before using it.

If the entire project syncs to the same repository, it is usually best to configure kup.repo in package.json.

How can I specify the id option more conveniently?

Kup can determine the id option in the following order of priority:

  1. The --id option passed on the command line.
  2. The id field in the Markdown file's metadata.

After a file is successfully published as an issue, Kup immediately writes the id back into its metadata.

How is the issue title determined?

Kup determines the issue title using the following hints, in descending priority:

  1. The title field in the Markdown file's metadata.
  2. If the first Markdown block is an H1 heading (in # Title form), Kup uses its text as the title. In this case, that H1 heading is excluded from the synced content.

What happens if Kup still cannot determine the issue title?

  • When publishing a new issue, Kup generates a title automatically.
  • When updating an existing issue, Kup ignores the title, which means the existing title will not be changed.

How do I assign labels to an issue?

Whether you are blogging or publishing regular issues, labels are often useful, so Kup supports them as well.

Add a tags field to the Markdown file's metadata and specify one or more labels. These labels do not need to exist in the GitHub repository beforehand. If a label does not already exist, it will be created automatically when the issue is published.

What happens if there is no tags field in the metadata?

  • When publishing a new issue, Kup will not assign any labels.
  • When updating an existing issue, Kup ignores labels, which means the existing labels will not be changed.

When updating an existing issue, if the labels specified in the metadata differ from the issue's current labels, the new set completely replaces the old one.

Documentation

Other

Roadmap

About the Name

  • Kup comes from the English word "pickup", suggesting lightweight transport.
  • Kup is also a character in Transformers.

About the Logo

License

Any code contributed to this project is considered authorized for commercial use by the project authors and their affiliated companies and distributed under this project's license.

任何贡献到本项目的代码，均视为授权本项目作者及其关联公司用于商业用途，并可按本项目协议进行分发。

MIT