Markdown Converter Plus

Markdown Converter Plus - Readme File

Contributors: Jo Landers
Donate to this plugin
Tags: plugin, development, markdown, parser, readme, shortcode
Requires at least: 2.8
Tested up to: 3.5
Stable tag: trunk

Parse readme files or use with shortcode to convert posts from Markdown to HTML.

Description [Top of Page]

Use as a Wordpress plugin to convert posts or pages written in Markdown (or a mixture of Markdown and HTML) to HTML by wrapping content in shortcode tags. Include in any coding project to process readme files or other documentation for on-screen display. Set defaults or send optional parameters to create navigation linking to all h2 tags within the content, 'step' header tags down a level if an h1 tag is present in the content, add download or contributor links, or convert screenshots lists into clickable image links. Includes an example function for software developers to include the class in their own plugin or other project (WordPress not needed). Wordpress-specific functions for running as a plugin are in separate files and only loaded if needed.

Features

• Parses database content, text files or both.
• Content can be a mix of Markdown and HTML.
• Can create a navigation bar on the page with links to all h2 tags, and add [top of page] links to your existing 'top' anchor or one it adds.
• Can add a target attribute to external links.
• If an h1 tag is present in the parsed content, can step all header tags down one level (preventing multiple h1 tags on a web page).

• Wordpress post or page content can be parsed using shortcode tags:

  [markdowntohtml]
  Entire post content here, which can include a mix of Markdown and html.
  [/markdowntohtml]

• See init() or the plugin options page for all available options.

Running as a Plugin

• Call as needed using a shortcode tag. If you run all content through a parser but only some contributors use Markdown, your pages should load faster, since only content in shortcode tags will go through the extra step.
• Defaults can be overridden on a per-post basis by sending a name="value" pair in the shortcode. Examples are included under each option on the Plugin Settings page.
• Adds contextual help or a help tab about using the shortcode to the WordPress posts and pages editing screens, and a link to the Markdown Syntax Documentation.
• The options page lets you change default settings, add a readme link on the Manage Plugins screen to any active plugin that has one, and view the readme files for all installed plugins.
• The options page includes a function to remove Markdown Converter Plus shortcode tags from database content (BACK UP the database FIRST). If you decide to deactivate or uninstall the plugin, do this first so 'orphaned' shortcode tags don't appear on your website pages.
• Readme files can be inserted into post pages (for example, to provide more information to users who can not access the plugins page):

Optional Introductory Content
[markdowntohtml plugin="my-plugin-folder"]
Optional Markdown Content
[/markdowntohtml]
Optional Closing Content

If you don't need to parse any additional content, you can use [markdowntohtml plugin="my-plugin-folder"] without the closing tag.

Using Shortcode Tags with Optional Parameters

The WordPress function to extract variables from shortcode tags is a little fussy. Shortcode tags MUST be separated by spaces (NOT commas), with NO additional spaces (except in values enclosed by quotes). If you send optional parameters in your shortcode tags and the result isn't what you expected, you probably have a stray space or comma in the shortcode.

Incorrect: [markdowntohtml db_navigation = "top", add_top_link = "true", top_link_text="Go Up"]

Correct: [markdowntohtml db_navigation="top" add_top_link="true" top_link_text="Go Up"]

Parsing Plugin Readme Files

• Converts WordPress-style Markdown (as shown in the plugin developer's example readme file) to standard Markdown for parsing.
• Checks the top section of a readme file (Contributors to Stable Tag) for the Markdown equivalent of a line break and adds any missing ones.
• Can convert 'Donate link:' to a clickable link.
• Can convert Screenshots lists to clickable links displaying the appropriate image in an inline 'popup' (uses Javascript).
• Can convert 'Contributors:' names to links when called with an array of names and links. You can set a list of defaults in init() or the Plugin Options page that apply to every file (for example, your own name and home page), and add others on a per-file or per-post basis as desired.
• Can add a download link to plugins or other packages available for download.

Using in Your Own Project

• Does not need WordPress.
• All variables are defined (and described) in init(), making it easy to set default values for your specific needs. Defaults can be overridden on a per-file basis by setting a new value in the params array when calling the class.
• Not just for readme files - can be used to display any documentation (including screenshots) from any text file by setting a file name and path relative to the default directory.

Installation [Top of Page]

1. Download markdown-converter-plus.zip and uncompress the file.
2. Upload the markdown-converter-plus folder to your plugins directory.
3. Go to the plugin management page of your site and activate the new plugin.
4. Go to the plugin settings page and change any defaults.
5. Add the following shortcode to any post formatted with Markdown:

[markdowntohtml]
Entire post content here, which can include a mix of Markdown and html.
[/markdowntohtml]

If you use this shortcode more than once per post, each block of content is processed separately. This increases the time it takes to load a single post, so, unless it causes a problem, you should wrap the entire post content in the tags and only call it once.

Screenshots [Top of Page] (please enable javascript to view screenshots)

1. The Plugin Options page.
2. This readme file in the WordPress admin area, showing a screenshot popup.
3. This readme file as a post on a WordPress site using the Twenty-Eleven theme.
4. The same file on my site, without WordPress.
5. User help on the 'Edit Post' page.

Frequently Asked Questions [Top of Page]

None yet. See the Additional Notes section for more information.

Additional Notes [Top of Page]

Known Issues in WordPress

See Michel Fortin's explanation of Wordpress Text Flow vs Markdown, which details how WordPress handles and saves post content and what PHP Markdown Extra (included in this plugin to parse the prepared content) does to accommodate this.

Adding Screenshots

• Screenshots must include 'screenshot' and a number in the name, with default 'gif', 'jpg', or 'png' file extensions. The required text 'screenshot' is set in init(). Default file extensions are set in init() or the plugin options page.
• A screenshots text block must start with 'Screenshots' (enclosed by markdown or html h2 tags) followed by an ordered list. The first screenshot is assigned to the first list item, followed by any additional list items and screenshots.
• Screenshot images must be in the same folder as the text file they relate to, or the optional parameters image_dir and image_url must be set with the complete path and url to the images folder.
• Unless the screenshots option is set to false, if there are screenshot image files the plugin will replace items in a screenshots list with an image link and add the necessary javascript to display the image as an inline 'popup'.

Adding other images, or including them outside the screenshots list

See the Markdown Syntax Documentation regarding inline images, or include an <img src= tag in your text file. The parser does not mind if you mix HTML and Markdown in a text file.

Formatting

The plugin applies the following formatting:

• All output is wrapped in <div class="markdown_converter_plus"> so you can apply your own styles targeting just the parsed content.
• Unordered lists are assigned class="ul-square" to get square bullets (my personal preference on those pages).
• Nav links use classes and inline styles to create a nav bar.
• Inline code spans have a background color, but code blocks (<pre><code>) do not.
• If $this->remove_h1 is set to true (to prevent multiple <h1> tags on a page), <h6> tags are replaced by <strong> and all higher <h tags are stepped down a level.

Inline styles are applied in add_formatting() in class_markdown.php as one of the last steps before parsed content is returned to the browser. You can suppress all inline styles by setting $this->apply_formatting to false in init() or changing it from the plugin options page. Headers are stepped down in step_headers_down() and can be left as-is by setting $this->remove_h1 to false in init() or changing it from the plugin options page.

Documentation in nested folders

If your project has several documentation files, you might want to make a documentation folder, with subfolders for each text file and any related images. For example, to format and display a file named 'usage_notes.txt' in 'documentation' folder, set the path parameter to my-project-folder/documentation/usage and the file parameter to usage_notes.txt or change the default path and url in init() to have those settings become the defaults for all text content.

Acknowledgements

Markdown Converter Plus uses PHP Markdown Extra © 2004-2009 Michel Fortin for parsing.

Example Function [Top of Page]

The minimum variables are $path and $file. If the text file belongs to download package, you can pass the complete download link and add it to the $params array:

function MyPlugin_markdowntohtml( $file='readme.txt', $path='my-path-relative-to-my-default-path', $download_link=false)
$params = array('file' => $file, 'path' => $path, 'download_link' => $download_link );

Note the call to __() at return sprintf(). This is used in WordPress for text translation. Markdown Converter Plus creates a replacement function if this doesn't exist, which simply sends the original text back.

There are several variables which can be sent to the function and included in the $params array to change the output on a per-file basis; see init() for a complete list and description of what each one does, and how to create different default settings for text files vs. database content.

function MyPlugin_markdowntohtml( $file='readme.txt', $path='my-path-relative-to-default' ) {       

    if ( substr($path, -1 ) != '/' ) $path = $path.'/';

    // if the class doesn't exist, try to add it
    if ( !class_exists('Markdown_Converter_Plus') ) {
        require('my-path-to-markdown/markdown-converter-plus/markdown-converter-plus.php');
    }
    if ( class_exists('Markdown_Converter_Plus') ) {
        $params = array('file' => $file, 'path' => $path);
        return $markdown2HTML->markdown_to_HTML($params);
    }   else    {   // the converter doesn't exist, return the text file
        $default_path = 'my-default-path'; // same as in init()
        if ( substr($default_path, -1 ) != '/' ) $default_path = $default_path.'/';
        $path = $default_path.$path;
        if ( !$content = @file_get_contents($path.$file) ) {
            return sprintf( __("The %s file was missing or unreadable"), $file);
        }   else    {
            return nl2br($content);
        }
    }   
}

If the class Markdown_Converter_Plus doesn't exist, this function will try to add it. If it can't, it will try to output the text file, replacing newlines with <br /> tags.

If you want to use shortcode tags in another content management system, you will need to modify the shortcode functions to match the ones used by your CMS, or write your own to determine when to call the parser. Optionally, you could run all database content through the parser without using shortcode tags. If you're interested in working on a class to extend Markdown Converter Plus to another CMS (Joomla, Drupal, etc.), please email me.

Upgrade Notice [Top of Page]

None.

Changelog [Top of Page]

v1.3 (10/12/12)

• Minor code and documentation changes.
• Tested under WordPress 3.4.2

v1.2 (1/22/12)

• Modified screenshot image preloading to use a stylesheet for preloading.
• Simplified javascript used to create screenshot popups.
• Tested under WordPress 3.3.1

v1.1 (12/6/11)

• Added support for help tabs in WordPress 3.3
• Tested under WordPress 3.3-RC1

v1.0 (11/20/11)

• Initial release, tested under WordPress versions 3.1 and 3.2.1