How can I test what my readme.md file will look like before committing to github?

Question

I am writing a readme for my github project in the .md format. Is there a way can I test what my readme.md file will look like before committing to github?

Solution 1

Many ways: If you're on a Mac, use Mou.

If you want to test in a browser, you could try StackEdit, as pointed out by @Aaron or Dillinger since Notepag seems to be down now. Personally I use Dillinger since it just works and saves all my documents in my browser's local database.

Solution 2

Atom works nicely out of the box - just open the Markdown file and hit Ctrl+Shift+M to toggle the Markdown preview panel next to it. It handles HTML and images also.

Solution 3

Visual Studio Code has the option to edit and preview md file changes. Since VS Code is platform independent, this would work for Windows, Mac and Linux.

To switch between views, press Ctrl+Shift+V in the editor. You can view the preview side-by-side (Ctrl+K V) with the file you are editing and see changes reflected in real-time as you edit.

Also...

Q: Does VS Code support GitHub Flavored Markdown?

A: No, VS Code targets the CommonMark Markdown specification using the markdown-it library. GitHub is moving toward the CommonMark specification.

The preview button is this:

More details here

Solution 4

This is a pretty old question, however since I stumbled upon it while searching the internet maybe my answer is useful to others. I just found a very useful CLI tool for rendering GitHub flavored markdown: grip. It uses GitHub's API, thus renders quite well.

Frankly, the developer of grip, has a more elaborate answer on these very similar questions:

• Is there a command line utility for rendering github flavored markdown?
• What's the best way to edit GitHub's Readme.md?

Solution 5

This one has proven reliable for quite some time: http://tmpvar.com/markdown.html

View more solutions

Comments

[Donnie D'Amato]

I'm answering this as a comment because the thread is closed and none of the solutions were rendering pipe tables the same way that github was. The web solution that seems closest is here: pandao.github.io/editor.md/en.html

[VonC]

With GitLab 13.0 (May 2020), the static site editor for GitLab has a WYSIWYG editor. See my answer below.

[VonC]

Since Nov. 2021, you can also use the new preview feature of a GitHub Gist to see what your Markdown will look like before adding, committing and pushing a copy to your local repository (and pushing to your GitHub README.md). See my answer below.

[DanielBell99]

Make sure you're using README .md and not README**.rst** for **StackEdit*8

[Ben]

It was off to a good start but then this one doesn't show horizontal rules...abandoned before further tests.

[Nikos Alexandris]

Nice for a quick-check though.

[Felix K.]

The problem with this solution is that GitHub (so far) shows inline diffs of the changes which makes a preview quite unusable if you want to get an impression of how the changes look like and not what actually changed.

[Aaron]

dillinger.io also seems to be down now, although it is still the first listed when you google "markdown online viewer", so it might just be me. I successfully used stackedit.io to preview and edit my readme.md.

[Emadpres]

Since I had local resources, like screenshots of app, this solution works best. Thanks!

[oneWorkingHeadphone]

Thank you! It's nice not to have to break my workflow and open a different editor or go to a different website

[PaulB]

I have been using atom for a year now and had no idea it could do that! Bring forth the shame nun...

[three]

Dillinger ist ok. Has been ok most of the time.

[Olkunmustafa]

StackEdit is great tool. Thank you!

[jmgarnier]

brew cask install atom

[Bruno Bronosky]

StackEdit formats "definition lists", github doesn't. StackEdit puts triple backtick code blocks on there own line (useful for use in numbered lists), github doesn't. There are other differences. The only safe bet is to trial and error with a gist and delete it when you are done.

[Mahmoud]

@B12Toaster You can create a new file on the repository using GitHub website (without saving it) and name it xxx.md and paste your code there. File extension is .md so you can preview your changes. You will update util you finish, then copy the file content and paste it over the original readme.md file.

[zhihong]

Used several tools before. And StackEdit is by now the one render most part like Github. Thanks

[aerin]

Nice!! I don't have to install atom!!

[Chris Priest]

Unfortunately it doesn't look like Mou support MacOS Mojave (10.14)

[Abel Callejo]

This works well because it supports github, gitlab, and generic markdown. Although it is difficult to install.

[Upio]

This should be the accepted answer - it's perfect! Just alt-tab between your editor and browser, and it will automatically re-render the markdown, and it looks exactly like it does on GitHub. Finally an acceptable solution.

[Nagev]

By the way, I wanted to test the link to titles used by GitHub (stackoverflow.com/a/45860695/5362795) and found that it's also supported by VS Code!

[austin]

perfs already had Atom installed just typed atom . and right clicked the readme > Markdown Preview

[David Parks]

Atom rules the roost. None of stackedit, Dillinger, or typora supported collapsible sections via HTML <details> tags. Atom does and looks better than the rest to boot.

[AFOC]

An additional issue is that it does not accurately display everything. One concrete example: if you are centering an image at the top using <div align='center'><img ...></div> it will not show it centered in the preview, it will be left-aligned. You have to save it to see it accurately, which makes the preview untrustworthy in my opinion.

[Spikatrix]

Ctrl+Shift+M didn't work for me for some reason. Had to open the command palette (Ctrl+Shift+P) and select markdown preview from there. Thanks!

[matteok]

MacDown is a great alternative to Mou. The developer states that the application is inspired by Mou so they are pretty similar. For me the transition was smooth macdown.uranusjr.com

[Keeely]

For the latest Pycharm it seems to support it out of the box (no plugins needed).

[randalv]

Correct - it's now built in to pycharm.

[DanielBell99]

Make sure you're using README .md and not README**.rst** for *StackEdit