Markdown Utilities

What is Markdown?

From the Markdown website: "Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)."

And what's this?

This here is a collection of a few more or less useful things which may be useful to Markdown users.

Markdown2html

This script for the command line which essentially does the same thing as Markdown.pl, but adds basic HTML header and footer. It's no rocket science, but it beats copying HTML headers and footers onto a Markdowned HTML file. Instant publishable hypertext documents.

Download

Installation

  • Download the current version of the Markdown2html script and extract it.
  • Move Markdown2html anywhere you please. Preferrably to a directory that is in your PATH.
  • If needed, apply chmod 755 Markdown2html.

Usage

Markdown2html expects input via standard input, just as Markdown.pl when used at the shell level. To convert a Markdowned text file, run the following comamnd in your shell:

cat my_file.text | Markdown2html > my_file.html

shift_headers.pl

A shell script that only has indirectly to do with Markdown. shift_headers.pl does not operate on Markdowned text but on HTML. Here it moves H1-H6 headings to a lower level.

This is extremely useful when combining multiple documents or when putting Markdown-formatted files into web sites. Your text files logically have the first heading as H1 (either by using a single # or by using the setext format), but in the context of another page, this should be H2 due to a site-wide H1 already on the page. So what to do? You can either go and take all the headings of the text file a level deeper, or you apply a little magic after the text has been converted to HTML.

Which is where shift_headers.pl comes in. You pipe HTML into it (just as you pipe Markdown-formatted text into Markdown.pl), and out comes the same HTML, but with all headings lowered one level. H6 of course can't be lowered any further (there is no H7), so they remain as they are.

The shifting code inside this shell script (you can use the function on its own if it suits your needs) was written by Michel Fortin and published on the Markdown discussion list. It made more sense than my own implementation, so I opted to use this instead.

Download

Installation

  • Download the current version of the script and extract it.
  • Move shift_headers.pl anywhere you please. Preferrably to a directory that is in your PATH.
  • If needed, apply chmod 755 shift_headers.pl.

Usage

Working with Markdowned files, the following command (in the terminal) is the quickest way of producing results:

cat my_file.text | Markdown.pl | shift_headers.pl 1 > my_file.html

cat outputs the contents of my_file.text. It is then piped into Markdown.pl, which goes ahead and makes HTML out of the text file. Then the HTML is piped into shift_headers.pl. Note that shift_headers.pl is called with the parameter "1". This means that all headings are to be "demoted" by one level.

If you instead want to take it down two levels, run shift_headers.pl 2. This will convert all <h1> to <h2>, all <h2>to <h3> and so on.

If the parameter is not between 0 and 5 (0 meaning nothin happens, 5 meaning all headings become <h6>), 1 will be used by default.

shift_headers.php

A PHP version with the same functionality as the Perl script above. Well, not quite the same. This PHP script does not function as a shell script. It is merely a function that can be included in a PHP script. It can then be called, passing it the HTML code as a parameter.

Download

Installation

  • Download the most recent version of the script.
  • Copy the shift_headers function into your code. It's up to you where to put it.
  • That's it.

Usage

To shift the headers of some HTML you want to putput, just call the shift_headers function with your original HTML code as the first parameter and an optional second parameter specifying the number of levels to shift. This can be a number from 1 to 5. Examples:

Shift the headers of the HTML code in $html two levels deeper. <h1> becomes <h3>.

$html = shift_headers ( $html, 2 );
print $html;

Read the contents of a Markdown formatted file, convert them to HTML and shift the headers by one level.

$Markdown = file_get_contents ( "syntax.text" );
$html = shift_headers ( Markdown($Markdown) );
print $html;

Version Histories

Markdown2html

  • 0.1 (2005-04-07) First version.

shift_headers.pl

  • 0.1 (2005-04-07) First version.

shift_headers.php

  • 0.1 (2005-04-07) First version.

etc

These scripts were built by Lasar Liepins

Markdown was conceived and implemented by John Gruber