Markdown

Table of Contents

What is markdown?

Markdown is a lightweight markup language, supposed to be pleasantly to write and read by humans

Description

Originally created by John Gruber and Aaron Swartz in 2004, Markdown allows people "to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML or HTML. It is used to make the sources of static web pages more human readable, and it is also more pleasant to write in than HTML. It is used as a markup language, for example at:

Variants

The original markdown specification from 2004 is only loosely defined. The commonmark specification is a strict definition of how to format a document using markdown. Besides this, many variants of markdown have evolved, each typically adding some features not included in the original. For example:

If you want to compare some variants and test whether they support some syntax, go to babelmark3

Markup languages similar to Markdown

  • txt2tags , implemented in Python, and supports output to HTML, XHTML, SGML, DocBook, LaTeX, Lout, Man page, Creole, Wikipedia/MediaWiki, Google Code Wiki, PmWiki, DokuWiki, MoinMoin, MagicPoint, PageMaker, AsciiDoc, ASCII Art, Plain text (HJG, 2013-09-22)
  • AsciiDoc with Asciidoctor
  • Creole
  • reStructuedText , the Python Documentation Generator]
  • Textile
  • ...

Tools

  • Caius (unmaintained, superseded by its fork in Tcllib): The CAIUS project has a pure Tcl package for processing Markdown.
  • CommonMark: A standardized version of Markdown. Also with Tcl bindings.
  • cmark: Tcl wrapper for CommonMark.
  • jimsoldout, TclSoldout: Jim, Tcl bindings to libsoldout.
  • Markdown2Go: Tcl/Tk application with the markdown converter (ported from Perl to tcl) together with the Caius extension (support for html tables).
  • shtmlview : Pure Tcl/Tk solution to display HTML and, via Tcllib's Markdown library, of Markdown in a Tk text widget.
  • tclhoedown: Tcl wrapper around Hoedown, a Markdown processor forked from Sundown (Sundown is no longer maintained).
  • Tcllib: Version 1.18 has a markdown module derived from tcl-markdown on github [L1 ].
  • Tclssg: Contains its own fork of the Caius Markdown package with bugfixes and an option to not convert tabs to spaces.
  • TclSundown (unmaintained): Tcl wrapper around Sundown, a Markdown processor (AK, Nov 9, 2014: I have a copy of Jeremy's Fossil repository. If anybody is interested I can put it up somewhere).

Applications

JOB - 2016-06-15 17:21:53

Utility script to convert all markup files in the current directory:

Prerequisites:

  • Perl must be installed on your machine,
  • markdown.pl again needs some more packages: html, json,...
package require Tk
catch {console show}

# convert to html using markdown

set dir [file dirname [info script]]

set mdcmd [file join $dir "util/Markdown.pl"]
set pattern "*.text"
set ext ".html"

# fix the directory name (required for glob under windows) ...
set basedir [string trimright [file join [file normalize $dir] { }]]

# execute markdown...

foreach f [glob -nocomplain -type {f r} -path $basedir $pattern] {

        # change file extension:
        set htmlfile [file rootname $f]
        append htmlfile $ext
        
        # puts "exec perl $mdcmd --html4tags $f > $htmlfile"
        eval exec perl $mdcmd --html4tags $f > $htmlfile &
}

# e.g. loading the browser...
set current_file [file join $dir "testfile.html"]
set command [list {*}[auto_execok start] {}]
exec {*}$command chrome $current_file &
puts "Done"
exit 0

The above script can be replaced by the following - a pure tcl markdown implementation available in tcllib as already described further up:

package require Tk
catch {console show}

# convert to html using markdown

set dir [file dirname [info script]]

lappend auto_path [file join $dir "lib"]

package require textutil
package require Markdown


set pattern "*.text"
set ext ".html"

# fix the directory name (required for glob under windows) ...
set basedir [string trimright [file join [file normalize $dir] { }]]

# execute markdown...

foreach f [glob -nocomplain -type {f r} -path $basedir $pattern] {

        # change file extension:
        set htmlfile [file rootname $f]
        append htmlfile $ext

        # slurp up the data file
        set fp [open $f "r"]
        set markup [read $fp]
        close $fp

        set fp [open $htmlfile "w"]
        puts -nonewline $fp [Markdown::convert $markup]
        close $fp
}

puts "Done"


if {1} {
        set current_file [file join $dir "testfile.html"]

        set command [list {*}[auto_execok start] {}]
        exec {*}$command chrome $current_file &
        exit 0
}