Github markdown previewing straight from your shell.
Ruby CSS HTML Shell
Latest commit 5a1b5ec Apr 16, 2016 @ianks Bump to 1.4.2 🎊

:octocat: octodown

GemVersion Build Status

Ever wanted to easily preview what your markdown would look like exactly on Github? Ever wanted to do that from inside of a Terminal?

Octodown uses the same parsers and CSS that Github uses for their markdown rendering. Github markdown styling looks beautiful, so it is Octodown's primary goal to reproduce it as faithfully as possible.

Octodown GIF


  • πŸ†• Edit your markdown like a boss with LiveReload.

    • octodown --live-reload
  • Uses the same markdown parsers and CSS as Github for true duplication.

    • Yes emojis are included. 😈
  • Fast. octodown uses native parsers to ensure performance.

  • Multiple CSS styles.

    • octodown --style atom
    • The github markdown (default)
    • The atom text editor markdown
  • Properly parses STDIN.

    • cat | octodown


Requirements: Ruby >= 2.0

  1. Install icu4c and cmake:

    • Mac: brew install icu4c cmake pkg-config
    • Apt: sudo apt-get install -y libicu-dev cmake pkg-config ruby-dev
  2. Install octodown:

    • If you have a non-system Ruby (highly recommended): gem install octodown
    • Else: sudo gem install octodown
  3. Install in VIM (optional):

    • Use Dispatch and add this to your ~/.vimrc:

      " Use octodown as default build command for Markdown files
      autocmd FileType markdown let b:dispatch = 'octodown --live-reload %'
    • Caveat: make sure you follow the directions on the Dispatch and make sure that the correct version of Ruby (the one which as Octodown install as a Gem), is used.


  1. Basic:

    • octodown
  2. Markdown preview styling:

    • octodown --style atom
  3. *nix lovers:

    • echo '# Hello world!' | octodown --raw > index.html
  4. LiveReload at http://localhost:4567:

    • octodown --live-reload --port 4567


  1. With no arguments given, octodown will read STDIN until EOF is reached.
    • In order to work with this mode, type what you want into the input, then press Ctrl-D when finished.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Run the test suite (bundle exec rake)
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request