Microsoft Markdown

Markdown for Microsoft Word. If you prefer text-based documentation(markdown, etc) over WYSIWYG(MS Word), then this is for you! Zack Wallace puts a collection of Windows Markdown editors through their paces, and comes away with a winner.

Overview

Markdown is a program that converts text files in to HTMLfragments. The text format understood by Markdown uses a minimum ofweird punctuation, which makes it more readable when editing it thanthe HTML is. At work when I have to write documentation, I haveswitched to using Markdown rather than writing raw HTML: it allows meto concentrate on the words rather than the coding side.

Markdown generates only the body of the page, not a complete document.This note describes the combination of make and sed I use tomanage collections of documents with common headers and footers.

Getting make and sed

The programs make and sed are standard-issue on Unix-likeoperating systems like GNU/Linux and Mac OS X.

On Windows XP, I use the nmake command that comes with MicrosoftVisual Studio .NET (use start button → All Programs → Microsoft VisualStudio.NET 2003 → Tools → Command Prompt to create a window with theenvironment variables set up right). For sed I use the Cygwinpackage, a collection of GNU utilities ported to Microsoft Windows.

Getting Markdown

On Windows, I unpacked the ZIP archive from the Daring Fireballproject page in to a directory of my C:Program Files andthen added the Markdown-1.0.1 directory to my Path environmentvariable (control panel → System → Advanced → Environment).This allows the use of markdown as a command.

On my Debian GNU/Linux box, apt-get install markdown does the trick.

I have not yet succeeded in installing Markdown on Mac OS X 10.2 ‘Jaguar’.This is slightly annoying because I do most of my writing at homeon my PowerBook. Up until now I have made do with a partialimplementation of Markdown in Python, but this is not very satisfactory.The funny thing is, John Gruber developed Markdown on Mac OS X…

Using make to format documents

Write documents as .txt files using a plain text editor (such asvi or Notepad). For example:

The exact number of equals signs under the titles does not matter.The important thing is that the page title, underlined with equalssigns, goes first in the document.

The simplest useful Makefile for Markdown would look like this:

The variable txtFiles lists all the .txt files in the directory.The command make all runs them all through Markdown. Theconventional make clean deletes all the HTML files.

The resulting HTML files are adequate (old versions of HTML did notrequire the document to be wrapped in html and body elements)but will look very plain.

Using `sed` to complete the HTML files

We want to wrap the ‘raw’ documents in extra HTML boilerplate. We dothis by adding sed to the mix: the last 2 lines of the Makefile ischanged to the following:

Now we create a sed script that adds HTML code before and afterthe output of Markdown. I admit I have to read the sed manualeach time I make one of these. It goes like this:

The first clause matches line 1 and replaces the h1 element with acomplete HTML preamble and head element. The contents of the h1is used for the document title, and additional metadata is read fromthe file metadata.inc, if it exists. Then the HTML code in fileheader.inc is appended.

The second clause happens on line 2: all it does is reinstate the h1element snarfed from line 1. Finally, the last line has footer.incand the HTML close tags appended to it.

The sed program does not care that these files do not exist yet; dothe command make clean; make and it will generate valid HTML fileswithout any additional mark-up.

Adding a stylesheet

Create a file metadata.inc containing the following:

After you rebuild the HTML files, they will have reference to thestyle sheet main.css. Add as many link and meta elements as youlike.

Adding header and footer

This is fairly obvious: create header.inc with something like thisas its contents:

Then add stuff to the CSS file to visually distinguish the header.(Arguably this is not particularly ‘semantic’ mark-up, but what thehey.) I also have a footer for this set of documents, that goessomething like this:

just for fun.

List of all the files

Here are links to the files used to make this here note:

Markdown Edit is a smart and powerful editor for markdown language. The latter is a simplified scripting language for more intuitive HMTL code creation. The program has a neat and simple interface with a dual window that enables real time live previewing of input and output formats. It provides many smart scripting aids such as syntax highlighting, snippets, drag and drop text and image into the code, multiple keyboard shortcuts and commands and many more. It has a rich array of configuration options and settings such as word wrap, remember cursor position, show scrollbars, show spaces, open last file, auto save, spell checking, ignore all caps, ignore markup tags and many more.a

Features

- Full-featured Markdown editor for Windows.
- Emphasis on content and keyboard shortcuts.
- Syntax highlighting and spell checking.
- Dual window for real time live preview.
- Real time (WYSIWYG) HTML code editing.
- Drag and drop images and text files.
- Smart snippets and word binding.
- Minimal interface with plenty of configurations.
- Assign keyboard shortcuts to many commands.

System Requirements

- 800 MHz central processing unit.
-