DEV Community 👩‍💻👨‍💻

Cover image for GitHub CLI extension to preview README.md
Yusuke Wada
Yusuke Wada

Posted on

GitHub CLI extension to preview README.md

Have you ever thought want to preview README.md before push to GitHub? I built the GitHub CLI extension to make it come true. It named gh-markdown-preview.

https://github.com/yusukebe/gh-markdown-preview

Features

  • NO-dependencies - You need gh command only.
  • Zero-configuration - You don't have to set the GitHub access token.
  • Looks exactly the same - You can see same as GitHub.
  • Live reloading - You don't need reload the browser.

Requirements

You have to install GitHub CLI before install.

$ brew install gh
Enter fullscreen mode Exit fullscreen mode

Installation

$ gh extension install yusukebe/gh-markdown-preview
Enter fullscreen mode Exit fullscreen mode

Usage

$ gh markdown-preview README.md
Enter fullscreen mode Exit fullscreen mode

Or this command will detect README file in the directory automatically.

$ gh markdown-preview
Enter fullscreen mode Exit fullscreen mode

Screenshot

Then access the local web server such as http://localhost:3333 with Chrome, Firefox, or Safari.

Screenshot

Available Options:

-p, --port     TCP port number of this server (default: 3333)
-r, --reload   Enable live reloading (default: false)
Enter fullscreen mode Exit fullscreen mode

gh markdown-preview is a GitHub CLI extension to preview your markdown such as README.md. The gh markdown-preview commnad start a local web server to serve your markdown document file with a GitHub style.

gh markdown-preview command shows the HTML got from GitHub official markdown API with the CSS extracted from GitHub web site. The styles are almost the same!

You can see rendered README before uploading to GitHub!

If you want to have more information, check this repository and give me a star:)

yusukebe/gh-markdown-preview: GitHub CLI extension to preview README looks the same as GitHub.

Top comments (0)

Timeless DEV post...

How to write a kickass README

Arguably the single most important piece of documentation for any open source project is the README. A good README not only informs people what the project does and who it is for but also how they use and contribute to it.

If you write a README without sufficient explanation of what your project does or how people can use it then it pretty much defeats the purpose of being open source as other developers are less likely to engage with or contribute towards it.