Home / Golang / Command Line

GitHub CLI extension to preview README looks the same as GitHub.

gh markdown-preview GitHub CLI extension to preview your markdown similar to the style of GitHub gh markdown-preview is a GitHub CLI extension to prev
Information
Category: Golang / Command Line
Watchers: 1
Star: 15
Fork: 0
Last update: Oct 26, 2021
Resource links
https://github.com/yusukebe/gh-markdown-preview

gh markdown-preview

GitHub CLI extension to preview your markdown similar to the style of GitHub :octocat:

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 show 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!

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.

Screenshots

Open your browser:

Screenshot of gh markdown-preview

Live reloading:

Screenshot of gh markdown-preview

Installation

$ gh extension install yusukebe/gh-markdown-preview

Upgrade:

$ gh extension upgrade markdown-preview

Usage

The usage:

$ gh markdown-preview README.md

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

$ gh markdown-preview

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

Available options:

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

gh markdown-preview command

Related projects

Author

Yusuke Wada http://github.com/yusukebe

License

Distributed under the MIT License.

0 Open More issues
Closed

Live Reloading Not Working

Both gh markdown-preview --reload gh markdown-preview -r are not working.

I'm using Ubuntu with WSL, it wasn't working on Firefox on Windows. I opened the Linux version but that didn't work either. I also tried Edge and nothing.

I'm editing my README.md inside Vim. I don't expect live changes but I expected changes everytime I save changes.

opened Nov 26, 2021 by Dosx001 18
Closed

Usage with emacs for multiple files

This is not an issue.

It's more of a thank you and a rudimentary emacs usage as I found this extension much more helpfull than using pandoc with emacs markdown mode on *nix like systems. I use this on Ubuntu 20.04.3 LTS and GNU Emacs 26.3.

Feel free to comment or just close this issue as you see fit.

To use this gh extension with emacs:

  1. insert into the .emacs file (or equivalent):
(defun md_preview ()
  "start /usr/bin/gh markdown-preview -p PORT <current buffer file>"
  (interactive)
  (let (PORT BFN BFN_PORT)
    (setq PORT (read-string "PORT: " nil nil "3333"))  
    (setq BFN (buffer-file-name))
    (setq BFN_PORT (concat BFN ":" PORT))
    (start-process "gh_markdown_preview" BFN_PORT "/usr/bin/gh" "markdown-preview" "-p" PORT BFN)))

(global-set-key [(control ?x) (p)] 'md_preview)
  1. restart emacs and open a couple of markdown files.
  2. to preview a buffer with a markdown file by using a web browser and the url http://localhost:3333: in emacs "C-x p" RET (to use the default port 3333)
  3. to preview a second buffer with a different markdown file in a web browser and the url http://localhost:3334: in emacs "C-x p" 3334 RET (or any port that isn't in use such as 3333 in this example)
  4. the lisp code above will put output from the gh markdown-preview instances into separate buffers named like /path/to/markdown-file.md:3333, /path/to/different-markdown-file.md:3334, etc. in emacs
  5. close the /path/to/markdown-file.md:3333 emacs buffer to exit the preview processes on port 3333 (and free the port)

This emacs implementation has shortcomings: A. The user must keep track of what port is open and available for use B. I'm not sure if this is the best solution if one is editing several hundred md files. I only edit a handful so I suspect it will work just fine for that. C. While I've used emacs for some time, the above is a first attempt at coding lisp. It works for me but there are likely many more shortcomings than A & B above. Treat this a place to start, not an end point.

HTH

and thanks again - it's really handy.

EDITs - the original code posted didn't work. The code above does, is a bit simpler, and perhaps makes it easier to keep track of what markdown file is being displayed on what port.

opened Jan 9, 2022 by stuart-nolan 4
Closed

Inconvenient URL output on startup

I'm on current Arch Linux with the current version of gh and this extension. On start, it outputs:

$ gh markdown-preview README.md
2022/04/07 15:27:37 Accepting connections at http://*:3333/
2022/04/07 15:27:37 Open http://*:3333/ on your browser
2022/04/07 15:27:37 GET [200] /
2022/04/07 15:27:37 Watching README.md for changes
2022/04/07 15:27:37 GET [404] /favicon.ico
2022/04/07 15:27:38 GET [200] /__/md

All other similar utilities (i.e grip for a specific example) that create a local web-server output a valid click-able URL in the terminal which you can just click on to conveniently jump to in your browser. I know the browser is automatically opened the first time but you may want to open it a second/later time. So please change that http://*:3333/ to http://localhost:3333/.

I suspect you may want to argue that http://*:3333/ informs the user that the port is opened globally but, as possibly another issue, I suggest from a security/privacy standpoint that the port should only be opened locally (i.e. on localhost) by default anyhow. Add another option -g/--global and thus for the rare case when a user needs this he obviously already knows what URL to use.

I've previously used grip but it has some annoying failures (currently broken with a Python error on Arch Linux) so I am looking for an alternative.

opened Apr 7, 2022 by bulletmark 3
Closed

How to switch dark/light mode?

My preview is always dark mode like this. Screen Shot 2021-12-03 at 13 56 00

Is there a way to switch light mode like your README? Screen Shot 2021-12-03 at 13 56 00

opened Dec 2, 2021 by mikanIchinose 2
Closed

Removed $, to improve copy & paste

null

opened Apr 14, 2022 by byaruhaf 1
Closed

feat: Live reloading as default

null

opened Jan 27, 2022 by yusukebe 1
Open

Add --export option like grip

Sometimes you just want to render a markdown file directly to a HTML file. grip provides an option to do this:

grip --export README.html

For this case, no server is started, no browser tab is opened, etc. Also can specify '-' for stdout.

Can this option please be added here?

opened May 12, 2022 by bulletmark 1
Open

it can not used on Windows 

>gh  markdown-preview test.md
--: C:\Users\lenovo\AppData\Local\GitHub CLI\extensions\gh-markdown-preview\gh-markdown-preview: /usr/bin/env: bad interpreter: Permission denied
opened May 5, 2022 by jthou 1
Open

Prepare default `/favicon.ico` ?

In most cases, there is no favicon.ico in our directory and it will be 404 not found. How about preparing the default favicon.ico and showing it as /favicon.ico.

SS

opened Apr 7, 2022 by yusukebe 0

Contents

    staltz Assert that an HTML string looks approximately the same as another HTML
    adam-golab Roadmap to becoming a React developer in 2019
    krishdevdb A Readme Template For Tomorrow's Opensource
    jeffwillette CLI readme viewer for GitHub repositories
    auchenberg A real browser preview inside your editor that you can debug.
    Dhaiwat10 Svelte port of @dhaiwat10/react-link-preview
    kefranabg 📄 CLI that generates beautiful README.md files
    brkckr A RecyclerView that looks like a TableView, can scroll horizontally and vertically with a fixed header at the same time.
    mislav GitHub CLI extension for fuzzy finding, quickly switching between and deleting branches.
    arturssmirnovs Github profile readme generator allows you to create nice and simple github profile readme files that will be included in your profile previews.
    DetegiCE May I show your ScoreSaber rank to GitHub readme?
    Ramotion :octocat: PreviewTransition is a simple preview gallery UI controller with animated tranisitions. Swift UI library made by @Ramotion - https://www.ramotion.com/agency/app-development/
    yangsheng6810 Org-latex-instant-preview provides instant preview of LaTeX snippets via MathJax outputed SVG.
    dameety vue-img-preview An image input preview component in vue 2
    aloisdeniel Approximate how your app looks and performs on another device.
    joshdsouza8 Pimp my README is an open source profile builder that you can use to add some cool components to your README profile - Made with <3 by webapp.io :)
    drewjbartlett vue-multivue - Use multiple vue apps of the same class on the same page.
    marco-rudolph This is the official repository to the WACV 2021 paper "Same Same But DifferNet: Semi-Supervised Defect Detection with Normalizing Flows" by Marco Rudolph, Bastian Wandt and Bodo Rosenhahn.
    ThreeCommaIO README snippets for Visual Code inspired by readme.so
    mislav GitHub CLI extension to copy a file from a GitHub repository locally without cloning the repository.
    livioribeiro cargo-readme - A cargo subcommand to generate README.md content from doc comments
    Share this repo

    Related Repos


    Command Line
    24
    an easy to use terminal styling library
    iskaa02 Qalam ✏️ Qalam is a Go library for easy terminal styling. Installation go get github.com/iskaa02/qalam Usage func main(){ // this will output "a red
     
    Command Line
    6
    Experimental go cli tool to track your open issues and PRs.
    suadev git-sum cli tool See open issue and pull request counts for each repository of the user. Installation go install github.com/suadev/[email protected] Usa
     
    Command Line
    5
    2048, but for the terminal
    Bios-Marcel 2048 terminal edition This a simple 2048 implementation running on the terminal. 2048.mp4 Using To build, go version 1.17 or later is required. After
     
    Command Line
    3
    mirror is command line tool for mirroring a web page.
    yusukebe mirror mirror is command line tool for mirroring a web page. Caution Do not abuse Demo Installation go install github.com/yusukebe/mirror/cmd/[email protected]
     
    Command Line
    8
    A golang TUI implementation of the popular word quiz wordle!
    TheDonDope Gordle A golang TUI implementation of the popular word quiz Wordle! System requirements A system dictionary must be installed. On debian based systems
     
    Command Line
    8
    Lint CLI for languagetool.
    skanehira languagetool-lint Lint CLI for languagetool. Requirements languagetool. Installation $ go install github.com/skanehira/[email protected] Use as
     
    Command Line
    9
    CLI for Shopware Account
    FriendsOfShopware Shopware CLI A cli which contains handy helpful commands for daily Shopware tasks Features Manage your Shopware account extensions in the CLI Build an
     
    Command Line
    101
    mango is a man-page generator for the Go flag, pflag, and cobra packages
    muesli mango mango is a man-page generator for the Go flag, pflag, and cobra packages. It extracts commands, flags, and arguments from your program and enabl
     
    Command Line
    24
    From the command line, quickly explore data from a CSV file.
    tmickleydoyle shallow-explore From the command line, quickly explore data from a CSV file. shallow-explore is a Golang backed command-line tool for iterating over c
     
    Command Line
    3
    Branch is a small CLI tool to automatically create git branches based tickets
    MaikelVeen ________ ________ ________ ________ ________ ___ ___ |\ __ \ |\ __ \ |\ __ \ |\ ___ \ |\ ___
     
    Command Line
    9
    neovim plugin search from the terminal
    neurosnap nvim.sh neovim plugin directory search from the terminal $ curl https://nvim.sh/s/statusline Name Stars OpenIssues Updated
     
    Command Line
    15
    A better kubectl explain
    kei6u kubectl-explore This is a plugin for kubectl to fuzzy-find and explain the field supported API resource. What kubectl-explore finds and explains the f
     
    Command Line
    62
    CLI client for Portainer
    greenled Portainer Stack Utils Table of contents Overview Mission Vision Supported Portainer API How to install How to use Configuration Inline flags Environme
     
    Command Line
    77
    A lightweight CLI tool for versioning data alongside source code and building data pipelin...
    kevin-hanselman Dud Website | Install | Getting Started | Source Code Dud is a lightweight tool for versioning data alongside source code and building data pipelines.
     
    Command Line
    157
    The Symfony CLI tool
    symfony-cli The Symfony binary is a must-have tool when developing Symfony applications on your local machine. It provides: The best way to create new Symfony app