Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

: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
  • 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 --stdin


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
  1. Install octodown:
  • If you have a non-system Ruby (highly recommended): gem install octodown
  • Else: sudo gem install octodown

Usage in VIM (optional):

  • Use asyncrun.vim:

    " Plug 'skywind3000/asyncrun.vim' in your vimrc or init.nvim
    :AsyncRun octodown %
    " or, run whenever a mardown document is opened
    autocmd FileType markdown :AsyncRun octodown %
  • Use Dispatch and add this to your ~/.vimrc:

    " Use octodown as default build command for Markdown files
    autocmd FileType markdown let b:dispatch = 'octodown %'
  • 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. Keeping it simple (choose your files from a menu):
  • octodown
  1. Markdown preview styling:
  • octodown --style atom
  1. Unix lovers:
  • echo '# Hello world!' | octodown --raw --stdin > index.html


  1. With --stdin, 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