What the World Needs is a Markdown IDE for Programmer Documentation

As an active JetBrains’ PhpStorm user one of my feature requests was for First Class WYSIWYG Markdown/Markdown Extra Support. Unfortunately they told me (and others) to use a 3rd party plugin which given it’s lack of quality and features turned out to be a non-starter for me. So I continue to use Markdown Pro which I love for what it is but I really need an order of magnitude more features.

But today I was thinking hard about how I’m going to implement documentation for the project I’ve worked on over the past 3 months without killing myself. A sad realization came over me that using MarkDown Pro would be very painful to use because it’s really nothing more than a glorified Notepad with Markdown support and a preview window; it has nothing to support me in the developer of documentation projects.

Then it hit me; what I really need is not an ability for PhpStorm to edit markup but instead a full-featured documentation IDE targeting programmers. And frankly I think the company best positioned to offer this would be JetBrains but I’d be happy to see any company offer it, if someone just will (Maybe those Sublime guys could…?)

So if you are from JetBrains or from some other company please consider the following feature set:


Here are just some of the features that I’d love to see a Documentation IDE support

  • Manage "Documentation Projects" vs. just individual markdown files.
  • Multi-pane editor like PhpStorm but with panes that support document creation.
    • Vertical or horizontal split edit and preview windows.
  • CSS-based Themes for preview.
  • File Watchers for post processing LESS, Saas another other features.
  • Version control support for Git, Mercurial, SVN, etc.
    • Support for docs in a subdir of a code repository or as independent repo.
  • Support for all major Markup/Markdown format including Different Dialects and HTML
    • Conversion between Markup/Markdown formats
    • Ability to configure all and/or specific documents to be edited in one format/dialect and saved in another.
  • Ability to Publish and Maintain Documentation Websites from DocStorm
    • Publish directly to GitHub Pages as well as maintain existing GitHub pages.
    • Publish to Evernote, DropBox, etc.
    • Offer "POST-To-Publish" feature that would allow us to publish and update using HTTP POSTs so that we could write our own server-side integrations to other locations besides GitHub such as CMS (WordPress, Ghost, etc), Wikis (Mediawiki, etc.), SaaS platforms and more using our own PHP, Ruby, Python, Node.js or other code server-side code.
  • Navigation Between Documents
    • Jump to Document via selected hyperlink
    • Jump to Section of Document via selected hyperlink+fragment
    • Jump to File by Name
    • Jump to Headings in Project (find by autocomplete)
  • Refactoring
    • Refactor Document Structure to change all affected links
      • If URL changes
      • If URL fragment changes
    • Move selected content into a new file and insert a link to the new file.
    • Provide a tree view of files and allow refactoring by drag-and-drop in tree view, with all necessary link fix-up.
  • Manage Images
    • As part of the project, relative to the project root
    • Enable images to be previewed inline
  • Search and Replace like the wonderful PhpStorm search & replace)
    • Regular expression search.
    • Highlight on up/down arrow of selected options.

Also potentially valuable would be integrations with existing documentation tools although I can’t yet envision exactly what that would look like:

Benefits to JetBrains

Back to JetBrains and why they should do this. Currently they have IDEs for Java, PHP, Ruby, Python and Javascript programmers and for the most part (I would assume) few of their customers cross over and purchase multiple tools. However if they were to offer a "DocStorm" then every one of their current IDE customers they might be able to up-sell a sizeable number of developers.

But even if they won’t do it, maybe someone else will? 


If you like this idea please vote for it on the JetBrains tracker

Update 9-Oct-2013

So JetBrains considered the idea, but decided against it. :-(  But they have changed their mind in the past if they’ve had enough requests, so please vote for both these tickets, if you will:

Better yet, if you are in the editor space and looking to expand your market, please consider building this flavor of your product and I expect you will find many new customers.


#1 Frank on 10.02.13 at 5:23am

Currently was it not possible to switch to PHPStorm, I use always Aptana - pure practice.
In Aptana it is possible to write MD, see http://www.winterwell.com/software/markdown-editor.php

Maybe this is a solution, there is a example for PHPStorm, a enhancement for your ticket.

#2 mikeschinkel on 10.02.13 at 9:42am

Hey Frank,

Thanks for the comment. Yeah, I tried Aptana when I first started but quickly switched to PhpStorm when it was release. Maybe they’ve improved Aptana a lot since then; they’ve sure improved PhpStorm in the same time period.

PhpStorm has a plugin for Markdown too, unfortunately its formatting is ugly — not like it would appear in HTML — and not very usable.

But what I really see a need for is a full IDE for developing documentation in Markdown; one that allows me to work on documentation projects with first class tools like PhpStorm and Aptana allow for working with PHP.

#3 Andrew Eddie on 11.18.13 at 6:30am

Let us know if you find a solution. I’m grappling with a similar problem. I did find this interesting little nugget: http://dillinger.io

It’s the first thing I’ve seen to recognise “`php. It doesn’t seem quite there yet but it would be great to just be able to link that up to a Github repo and create a documentation site.

#4 mikeschinkel on 11.18.13 at 7:23am

Hi @Andrew,

Thanks for the comment, and sure thing. I do hope some IDE vendor will eventually address this.

And if you have not already, please vote up this request to show them there is interest (especially the first one):


#5 Jurgen on 09.07.15 at 12:05pm

Over time you should see more and more sophisticated markdown plugins for extensible editors like Atom.

In the meantime, a site generator like pub-server (sorry, shameless plug) can produce a complete doc website with navigation and with custom design if you need it, from a directory of markdown files.

pub-server will also watch the directory and auto-update a browser preview every time you save a file using your favorite markdown editor.


#6 mikeschinkel on 09.07.15 at 5:39pm

Hi @Jürgen,

Thanks for the comment, and great catching up last night.

Here, I’ll include a link to your Github for you: pub-server.

Best of luck with it!


Leave a Comment