PhpStorm 8: Markdown Support in PHPDoc Blocks

Posted on by rustam.vishnyakov

Since PhpDocumentor allows Markdown in documentation blocks (as stated here), we have added Markdown support to PhpStorm 8 too when showing a quick documentation of classes, functions, etc. Here is a list of what is actually supported from Markdown syntax specification, with some examples:

  • Paragraphs separated by one or more line breaks. There is a continuous flow of text inside a paragraph without line breaks from the original description.
  • Headers. You can use the following style, for example:
    My Header  OR  My Header
    ---------      =========

    or use the number sign (#):

    # My Header 1
    ## My Header 2
  • Emphasis. A piece of text surrounded with underscore characters (_) or asterisks (*) is rendered as underlined. You can also use double asterisks (**) to make it bold. Note that if the underscore character appears inside a name, for example my_variable, it is left as is.
  • Lists. You can use asterisks (*) or short dashes (-) at the beginning of a line to mark a list item. For example:
    ...
    * * First item
    * * Second item
    * * Third item

    These will be translated to an HTML list as follows:

    • First item
    • Second item
    • Third item
  • Code blocks. Wrap the code into backtick quotes () as follows: <pre>*
    * // This is a code fragment
    * $this->x = 0;
    * </pre> </li> </ul> <em>Note</em>: It is possible to use HTML markup in combination with Markdown. And finally, a larger sample: <pre><code> /** * # MyClass Documentation * * Describes _how to use_ the class with some examples: *
    * // Create new instance
    * $obj = new MyClass();
    * * HTML tags are properly escaped: *
    * <html><div></div></html>
    * `
    * Steps:
    * * Step 1
    * * Step 2
    * * Step 3
    *
    * **Note:** <i>Some important note.</i>
    */

    The example above will be rendered like so:

    phpdoc_render_sample

    If you find anything that can be improved or is not working as expected, please share your feedback in the issue tracker. Thanks!

    Develop with pleasure!
    -JetBrains PhpStorm Team

Comments below can no longer be edited.

13 Responses to PhpStorm 8: Markdown Support in PHPDoc Blocks

  1. Yakir Sitbon says:

    April 4, 2014

    How I can use with this? I do not get any autocomplate or preview in my PHPDoc from the editor.

    Thanks.

    • rustam.vishnyakov says:

      April 4, 2014

      It works in a quick documentation window (default shortcut Ctrl+Q). Basically you need to navigate to function/class and open the documentation window using the mentioned shortcut.

    • Yakir Sitbon says:

      April 4, 2014

      Sorry. This is get from CTRL+Q. Nice job 🙂

    • Callum Macrae says:

      April 4, 2014

      Are you using PhpStorm 8 EAP? The current stable release of PhpStorm (7.1) doesn’t have this functionality.

      • Callum Macrae says:

        April 4, 2014

        Can’t delete my comment, I was slow 🙁

      • Mikhail Vink says:

        April 4, 2014

        Yes, PhpStorm 8 EAP, this feature is there. Version is mentioned in title of the blog post and intro.

  2. MaximAL says:

    April 7, 2014

    Underscores in Markdown are for italics. Aren’t they?

    • rustam.vishnyakov says:

      April 7, 2014

      Both * and _ are translated to <em> which is just a semantic tag. Although you are right, browsers show a text inside <em> as italic.

      • MaximAL says:

        April 7, 2014

        I mean emphasis, of course.
        IMHO, ems are preferable to be italics in PhpDocs by default.

    • rustam.vishnyakov says:

      April 10, 2014

      Changed to italic (will be in EAP build after 136.1575)

  3. PhpStorm 8 - New Features says:

    June 6, 2014

    […] comment blocks. You can read the details of this implementation, as well as see a demo use case, in this post. Markdown was implemented due to PhpDocumentor’s support of MarkDown as stated here, but it’s […]

Subscribe

Subscribe for updates