Is there a command line utility for rendering GitHub flavored Markdown?
Solution 1
I wrote a small CLI in Python and added GFM support. It's called Grip (Github Readme Instant Preview).
Install it with:
$ pip install grip
And to use it, simply:
$ grip
Then visit localhost:5000
to view the readme.md
file at that location.
You can also specify your own file:
$ grip CHANGES.md
And change port:
$ grip 8080
And of course, specifically render GitHub-Flavored Markdown, optionally with repository context:
$ grip --gfm --context=username/repo issue.md
Notable features:
- Renders pages to appear exactly like on GitHub
- Fenced blocks
- Python API
- Navigate between linked files (thanks, vladwing!) added in 2.0
- Export to a single file (thanks, iliggio!) added in 2.0
-
New: Read from
stdin
and export tostdout
added in 3.0
Hope this helps someone here. Check it out.
Solution 2
I've not found a quick and easy method for GitHub-flavoured Markdown, but I have found a slightly more generic version - Pandoc. It converts from/to a number of formats, including Markdown, Rest, HTML and others.
I've also developed a Makefile
to convert all .md files to .html (in large part to the example at Writing, Markdown and Pandoc):
# 'Makefile'
MARKDOWN = pandoc --from gfm --to html --standalone
all: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile
clean:
rm -f $(patsubst %.md,%.html,$(wildcard *.md))
rm -f *.bak *~
%.html: %.md
$(MARKDOWN) $< --output $@
Solution 3
pip3 install --user markdown
python3 -m markdown readme.md > readme.html
It doesn't handle GitHub extensions, but it is better than nothing. I believe you can extend the module to handle the GitHub additions.
Solution 4
Maybe this might help:
gem install github-markdown
No documentation exists, but I got it from the gollum documentation. Looking at rubydoc.info, it looks like you can use:
require 'github/markdown'
puts GitHub::Markdown.render_gfm('your markdown string')
in your Ruby code. You can wrap that easily in a script to turn it into a command line utility:
#!/usr/bin/env ruby
# render.rb
require 'github/markdown'
puts GitHub::Markdown.render_gfm File.read(ARGV[0])
Execute it with ./render.rb path/to/my/markdown/file.md
. Note that this is not safe for use in production without sanitization.
Solution 5
To read a README.md file in the terminal I use:
pandoc README.md | lynx -stdin
Pandoc outputs it in HTML format, which Lynx renders in your terminal.
It works great: It fills my terminal, shortcuts are shown below, I can scroll through, and the links work! There is only one font size though, but the colors + indentation + alignment make up for that.
Installation:
- apt:
sudo apt-get install pandoc lynx
- nix:
nix-shell -p pandoc lynx
McLeopold
Updated on July 10, 2021Comments
-
McLeopold almost 3 years
I'm wondering if there is a command line utility for taking a GitHub flavored Markdown file and rendering it to HTML.
I'm using a GitHub wiki to create website content. I've cloned the repository on my server and would then like to process it into regular HTML. It's important to me that what appears on GitHub is exactly how it should look for my website. I'd also really like to use the fenced blocks with
~~~
, so I'd rather not use standard Markdown syntax only.I've looked a bit into the JavaScript live preview thinking I could hook it into Node.js, but they say it is deprecated. I've looked at the redcarpet repository, but it doesn't look like it has a command line interface.
I rolled my own solution, however, since no solution here is clearly better than the others, I'll leave the question without a selected answer.
-
Lazy Badger over 12 yearsHaven't ideas - I don't write Ruby and I didn't read Redcarpet sources
-
RichVel about 11 yearsWorks really well and you can't beat ease of install for Pythonistas!
-
Bluu about 11 yearsThis should be a first hit for "github markdown preview." Everything else is complicated, doesn't work, or doesn't do all the GitHub features.
grip
works right out of the box. -
ProfHase85 almost 11 yearsThanks for the hint, a real great package. Is there a reason why there is no HTML (css-inclusive) export?
-
bguiz almost 11 yearsI've noticed that this doesn't support features like syntax highlighting for code blocks and newer features like checklists. But hey it gets most of the way!
-
Houdini over 10 yearsDoes this work with Python3.x? Because I tried installing, and it seems like it may have a dependency on
flask
, which does not appear to be supported with Python3.x. See github.com/mitsuhiko/flask/issues/339 -
Joe over 10 years@Houdini That issue is out of date. Flask does support 3.3, see flask.pocoo.org/docs/python3. Here's a more recent Github thread on the topic github.com/mitsuhiko/flask/issues/587. If there's another dependency that needs updated, feel free to open an issue or a pull request.
-
Brad Parks over 10 yearsi've been using "watch pandoc ..." to continuously convert a markdown file to html, and the chrome "live reload" extension to get real time "stay where i'm scrolled too" functionality with this, and it works great. chrome.google.com/webstore/detail/livereload/…
-
Gabriel Llamas over 10 yearsI know, the module has not been udated in 9 months, why do you downvote an old post?
-
Keith Bennett over 10 yearsI tried this with fenced blocks for Ruby and Cucumber. While the fences (
ruby,
cucumber, etc.) appear to be recognized as fences (because they're rendered in fixed width text), there is no syntax highlighting. Any idea why? -
Kazimieras Aliulis about 10 years/usr/bin/python: markdown is a package and cannot be directly executed
-
Greg about 10 yearstmpvar doesn't seem to do GFM version enhancements like tables
-
Xandaros over 9 yearsVery nice, the only thing I'm missing is some borders for the tables. Well, at least I can render them at all, this is pretty much exactly what I need. Pipe in the GFM, pipe out HTML :)
-
Cora Middleton over 9 yearsThe question is specifically about command-line usage. Before writing your own ruby script (or egad node server), give this a shot.
-
Barry Staes over 9 yearsExactly this works inside your terminal. Or if your favorite (desktop?) browser can access that folder use
pandoc readme.md -o readme.md.html
and open the resulting file. -
Cora Middleton over 9 years@baerry-staes Yes, sorry, I hope it was clear that yours was my favored answer.
-
Barry Staes over 9 years@JustinMiddleton yes i got that, thank you. My comment was just to add some extra info for desktop users.. i figured someone someday reading this might find it useful.
-
prashant about 9 yearsPandoc reads GFM fine but it doesn't generate the same HTML GitHub does -- for instance, if you have a multi-line
<pre/>
tag in your GFM source, Pandoc will put<br/>
tags in for the line breaks in it, while GitHub's renderer, though it strips leading whitespace, seems to otherwise leave the content alone. -
leo about 9 yearsIt should be noted that this package requires an active internet connection and your github authentication credentials (provided at command line) if you do more than 60 refreshes per hour.
-
Joe about 9 years@leo You can use a personal auth token instead of your credentials. That's actually recommended instead of exposing your password. github.com/joeyespo/grip#access
-
Halil Kaskavalci about 9 yearsSimple HTML output with no fancy tags.
-
VIGNESH about 9 years
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
-
jedd.ahyoung almost 9 yearsWell done, man. Saves me from having to resort to Ruby or Python when I'm writing a node application, which is great.
-
plesatejvlk almost 9 yearsThanks Jim, due to virtually non-existent examples, I was stuck at the require step (replacing dash with slash made it).. ;)
-
Gourneau almost 9 yearsThis is great for creating local mirrors of Github wikis. First clone your wiki by running this command like this (replace .git with .wiki)
git clone https://github.com/user/project.wiki
. Then you can host it locally with grip for a killer combo :) -
spren9er over 8 yearsIn Atom you can install a package called gfm-pdf (atom.io/packages/gfm-pdf), which exports your markdown document to a HTML and/or PDF document. The library wkhtmltopdf is required.
-
Joe over 8 years@Gourneau Thanks for sharing! Just added a 'Tips' section to the Readme with this github.com/joeyespo/grip#tips :-)
-
Jez over 8 yearsAs mentioned earlier, I don't think this is a particularly great solution because all it does it goes off to Github and gets Github to render your Markdown. It requires a working internet connection with access to Github, and if Github dies then this tool stops working. I'd rather have a completely offline solution.
-
yyny over 8 years@VebjornLjosa * that * or
grip
... You chose. :P -
yobiscus over 8 yearsFor debian users, you can run grip via
python -m grip [options]
, since there is no executable placed in the PATH directories. -
Pacerier over 8 years@LazyBadger, Sundown is the actual parser (written in C). Redcarpet is not needed.
-
kayleeFrye_onDeck about 8 yearsThis is great if you're already using NPM. I had to use it, on account of DOxygen causing me constant problems with specifically github-flavored markdown + exporting to HTML.
-
kayleeFrye_onDeck about 8 yearsYou guys still supporting this? I tried to install with NPM today, but no dice. >downloading electron-v0.36.9-win32-x64.zip >Error: self signed certificate
-
Yoshua Wuyts about 8 yearsYeah, we are! What version of npm / node did you run this on? - feel free to open up an issue on GH and we'll take a look at this. Thanks!
-
AlanObject almost 8 yearsI got grip 4.2.0 from a pip install and it works as a server but the --export function doesn't work. It just hangs. Anyone else have this problem? Of course if you want an HTML file you can always save-as from the browser.
-
Joe almost 8 years@AlanObject There's an issue that was recently opened that I think is related. (github.com/joeyespo/grip/issues/180) I'll take a look at it next week! Feel free to comment there or open a new issue anyway to make sure the specific issue you're seeing is addressed.
-
Dominik George over 7 years
apt-get isntall pandoc
will do, no need to use insecure, local stuff like brew. -
Federico Tomassetti over 7 years@DominikGeorge there is a typo, it is install, not isntall
-
richrad over 7 years@DominikGeorge there's no apt-get on macOS.
-
Stuart Rossiter over 7 yearsLatest 4.3.2 for me (on Windows) only supports page links with an explicit
.md
suffix (rather than the normal syntax of just the page name). Am I missing something here? -
Stuart Rossiter over 7 yearsHmm this says the
[link text](link URL)
format I was using should always be the full URL (i.e. with the suffix). Yet GitHub allows it not to have the.md
suffix and work. -
Stuart Rossiter over 7 years...and including the suffix on GitHub gives me a link to the raw source of the page, not it rendered (i.e., I have to use the suffix-less links). Huh?
-
Joe over 7 years@StuartRossiter Want to open an issue? I'd be happy to look into it. It might be easier to drill down into the details there instead of in comments here github.com/joeyespo/grip/issues
-
kidmose almost 6 yearsWith pandoc 1.16.0.2 on linux mint 18 I get an error:
pandoc: Unknown reader: gfm
. Going to 2.2.1 fixes this. -
Asme Just almost 6 yearsI tested it with Pandoc 2.1.2.
-
Holistic Developer almost 6 yearsHow does one go about getting nice styling on the resulting HTML? My output is still rendered with Times New Roman, for example.
-
memoselyk over 5 yearsI think this is the "closest to source" answer from all of them since these tools are the ones used by github.
-
Master of Ducks over 5 yearsPandoc install instructions are here. On macOS:
brew install pandoc
-
JESii over 5 yearsUnfortunately, it doesn't seem to support GFM tables which is what I need.
-
Alexander Mills over 5 yearshow to install 2.2.1 on ubuntu?
-
Asme Just over 5 years@AlexanderMills Did you try
sudo apt install pandoc
? -
Russ Brown almost 5 yearsI've tried about 5-6 other console md readers and this has by far been the best solution. I just added the most basic function to my config to make it a little quicker to use.
function md { pandoc $@ | lynx -stdin }
-
Alexander Oh almost 5 yearsnice tool! I was expecting something that would render it in the cli though.
-
user5359531 over 4 yearsis this running locally or is it sending data out to GitHub API?
-
user5359531 over 4 yearsneither the
gfm
nor themarkdown_github
input formats correctly render things like code blocks. -
user5359531 over 4 yearsit also does not correctly interpret the YAML or pandoc header metadata blocks
-
Matthew over 4 yearsI'm confused about this example, what is
^D
? -
stevec over 3 yearsThis is arguably the best solution, but you don't give actual instructions on what to do. So after installing the gem
gem install redcarpet
, suppose we're in a directory containingREADME.md
what next? -
Alexander Kucheryuk over 2 years
grip
is amazing. But, unfortunately, due to its name it is not possible to find it easily if you forget how it is named. (not available via MacPorts either). -
Boris Verkhovskiy over 2 yearsStrictly speaking, this is "John Gruber's Markdown", not GitHub flavored Markdown.
-
Boris Verkhovskiy over 2 yearspandoc's output downloads a file from Cloudflare for IE 9 compatibility
-
wisbucky over 2 years@AlexanderOh You can output to file with
grip file.md --export file.html
-
wisbucky over 2 yearsPretty cool tool since it uses Github API, so it's an exact rendering. One inherent downside is that it adds a ton of css and header code.