Search

A new extension, “Markdown Guide” is now available for download. Comments and feedback can be left here but if you discover any issues, please post it on the issue tracker.

This extension adds a condensed markdown syntax guide immediately below all textarea fields that use one of the markdown text formatters. This might be helpful for someone new to markdown, but it might be just clutter for an experienced markdown user.

This extension is similar in intent to the Textformatter Labels extension. The principal difference is that Textformatter Labels provides a link to a full guide on the web, while Markdown Guide displays a condensed version of the guide right on the edit form. You can choose the one that suits you best or use both at the same time (or neither of course).

Extension works in symphony 2.0.6

Added a fork to this extension that add a colapse button to show/hide the guide.

@guillem_I: I tried your collapse button fork but didn’t get a button — or I don’t know where to look for it.

Hi there!

Really want to use this extension as I’m new to Markdown, but I couldn’t get it to work on 2.0.8RC3

Here’s what I did to get it working:

Firstly, I found that the textareas don’t have pb_markdown as the formatter, instead, it is one of the following

  • markdown
  • markdown_extra
  • markdown_extra_with_smartypants
  • markdown_with_purifier

So I altered the function slightly to incorporate this, so that the guide could be applied to all Markdown fields, not just plain Markdown. I’ve also added the ability to use different guides per formatter, if the need arises…

    public function addGuideBelowTextArea($pointer) {
    //only show guide when using markdown
    $formatter = $pointer['field']->get('formatter');
    $pattern = '/^markdown/';
    if (!preg_match($pattern, $formatter)) return;

    //append the textarea here so the guide will show after the textarea in the form
    $pointer['label']->appendChild($pointer['textarea']);

    //nullify the textarea to prevent another one being appended in field.textarea.php
    $pointer['textarea'] = Widget::Label('');

    //retrieve the guide and append it
    switch($formatter){
        case 'markdown':
            $file = DOCROOT . '/extensions/markdown_guide/guide.txt';
        break;
        case 'markdown_extra':
            $file = DOCROOT . '/extensions/markdown_guide/guide.txt';
        break;
        case 'markdown_extra_with_smartypants':
            $file = DOCROOT . '/extensions/markdown_guide/guide.txt';
        break;
        case 'markdown_with_purifier':
            $file = DOCROOT . '/extensions/markdown_guide/guide.txt';
        break;          
    }

    $contents = file_get_contents($file);
    $guide = Widget::Label($contents);
    $pointer['label']->appendChild($guide);
}

}

I’ve left all the text files referenced to guide.txt, but they can be changed per formatter to give different files.

EDIT: changed the guide filenames in the zip posted below.

I’ve pulled in guillem_l’s changes too, and zipped it all up.

Carson, to get guillem_l’s changes to work, I had to uninstall the extension the re-enable it to get Symphony to register the delegate callback’s

Hope this is all useful?!

PS, I would fork all this, but I aint got Github…

Attachments:
markdown_guide.zip

It’s working for me in 2.0.8RC3.

I’ll review and test your changes and then merge them into my github repository.

Thanks.

I’ve found that the reason it has been working for me and not you is that I was using an old version of Markdown Text Formatter. In a later version Alistair renamed the formatters in the code. I don’t know why I had the old version since I have been updating the submodules as I pick up new versions of Symphony.

Yeah, I thought that myself. Wondered why there was a translation going on in the formatter.

Glad it’s sorted though, it’s a very useful extension!!

Markdown Guide updated to version 1.1 on 8th of June 2010

Incorporated changes suggested by designermonkey and guillem_l.

Added a zip file for those who don’t use github.

Don’t forget to change the version number in extension.driver.php. Thanks for this nice extension!

I also created a formatted version of the guide so it looks a little nicer. Just edit the txt files in the assets folder.

markdown_extra_with_smartypants.txt

<ul style="border:1px solid #E4E4DE; padding:10px 10px 10px 25px; margin:10px 0px; background-color:#F5F5F3;">
    <li><strong>Headers:</strong> Precede with a # for each level desired as in: ### This is an h3 header</li>
    <li><strong>Paragraphs:</strong> Seperate with a blank line</li>
    <li><strong>Blockquotes:</strong> Precede with a >  (two >> will produce a quote within a quote)</li>
    <li><strong>Unorderd lists:</strong> Precede list items with a *, + or -</li>
    <li><strong>Ordered lists:</strong> Precede list items with a number followed by a period</li>
    <li><strong>Emphasis:</strong> *italics*  **bold**  or  _italics_  __bold__</li>
    <li><strong>Links:</strong> [link text](http://some-site.com "optional title")</li>
    <li><strong>Automatic links:</strong> Enclose a URL in angle brackets to produce a link using the URL itself as the link text</li>
    <li><strong>Images:</strong> ![alternate text](/path/to/img.jpg "optional title")</li>
    <li><strong>Code blocks:</strong> Indent each line of the block by at least 4 spaces or one tab</li>
    <li><strong>Inline code:</strong> Wrap the code with backtick characters</li>
    <li><strong>Horizontal rules:</strong> Place 3 or more asterisks, hyphens or underscores on a line by itself</li>
    <li><strong>Line breaks:</strong> To force a line break, end the line with 2 spaces and then start a new line</li>
    <li><strong>Backslash escapes:</strong> To force a literal display of special markdown characters, precede with a backslash</li>
</ul>

Thanks for the reminder and the styling suggestion. But, I found that some of your styling interferes with the operation of the show-hide toggle. I was able to use the strong tags. When I have time to fix the toggling I will add the remainder of your styling.

But, I found that some of your styling interferes with the operation of the show-hide toggle.

It does? I didn’t notice in Chrome or Safari … I see what you mean in Firefox. Sorry! I didn’t do my browser testing before posting.

No problem. Most of the time I only test in Firefox.

Markdown Guide updated to version 1.2 on 27th of July 2010

@phoque - I pulled your fork of this extension and took a look at it. Thank you for adding the localization feature. But I can’t get it to translate. I changed my language to Deutsch but the guide still displays in English. What do I have to do to get it to display in German?

Localization is new to me so can you point out where the translation is supposed to occur in the code?

Strange, it’s working fine for me. Do you have Nils’ lang_german installed?

Localization is done in the __() function, all localized strings are in lang/lang.de.php.

I did not have lang_german installed. I installed it and found that it made no difference and that the markdown guide translation is not dependent on it.

I discovered that translation was not working because I didn’t have markdown guide enabled. That brings up another issue: Why is it displaying at all when it is not enabled? Apparently I’ve left something out of the extension.

Edit: I disabled the extension and now it doesn’t display the guide (as expected). The extension enable-disable process must be a bit quirky.

Create an account or sign in to comment.

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details