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)
- 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.
- Refactor Document Structure to change all affected links
- 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:
- PHP: PhpDocumentor, ApiGen, etc.
- Ruby: RDoc, Yard, etc.
- Python: PyDOC, Sphinx, etc.
- Java: JavaDoc, Doxygen, etc.
- APIs: Swagger, Apiary.io, etc.
Benefits to JetBrains
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
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:
- Vote for WI-20326! – "Launch New Product: "DocStorm" IDE for Markdown/Project Docs"
- Vote for IDEA-107084! – "First Class WYSIWYG Markdown/Markdown Extra Support"
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.
7 Replies to “What the World Needs is a Markdown IDE for Programmer Documentation”
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.
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.
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.
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):
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.
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!
in recent months, I worked on a standalone application aiming to be more than just Markdown notepad. Although it doesn’t have all the features you are looking for (I just did the first release), it enables IDE-style work e.g.:
– it is able to open any number of Markdown documents to search, browse, read and edit – it scans path/directory you provide and finds all the Markdowns in (sub)directories
– it previews Markdown document as outline – you can easily refactor sections (move/up/down/promote/demote/…)
– it provides refactoring, cloning and extraction – you can refactor Markdown document and/or section to other Markdown document and/or section
– it brings OOTB set of Markdown document/section stencils/templates that can be easily extended with your own
… and more. Check
http://www.mindforger.com and/or https://github.com/dvorka/mindforger
Please let me know what you think.