Markdown Service Tools 1.0   
(c)2010 Brett Terpstra   
<mailto:me@brettterpstra.com>   
<http://brettterpstra.com>   

View this [document as HTML](http://brettterpstra.com/code/markdown-service-tools/).

![screenshot](http://brettterpstra.com/wp-content/uploads/2011/01/MarkdownServiceToolsScreenshot.jpg "Markdown Service Tools")

# Markdown Service Tools

Markdown Service Tools is a collection of OS X Services to make creating Markdown-formatted text that much easier. Services work in any Cocoa based application (which is most of the apps on your Mac). These Services were tested on Snow Leopard, but should work fine on Leopard... maybe even Tiger. They're each prefixed with "md" to keep them together in your Services menu, and you can assign your own keyboard shortcuts (see last section of this document) to make accessing them convenient while typing. The following Services are included:

* md - Bold
* md - Bullet List
* md - Preserve Line Breaks
* md - Indent Selection
* md - Italics
* md - Link List From Clipboard
* md - Link Selection
* md - Links From Chrome Tabs
* md - Links from Safari Tabs
* md - Ordered List
* md - Outdent
* md - Wrap Parenthesis
* md - Wrap Square Brackets
* md - Inline Links to References
* md - HTML to Clipboard
* md - Clean up lists
* md - Clean up tables
* MultiMarkdown to HTML
* Auto-link web search

Note: *some Services are only available when text is selected, and some only when *no* text is selected but a text field is focused.*

### Descriptions ###

*The suggested key bindings in each description are just what work for me, personally; there's no consequence for using something completely different. Just be aware that an application's default keyboard commands will override any in the Services menu, so a command's shortcut may become unavailable if it's already in use by the current application.*

**Bold/Italics**
: These simply wrap selected text in Markdown emphasis syntax. `*` for italics, `**` for bold.
: **Suggested key bindings:** Command-Shift-B (bold) and Command-Shift-I (italics)

**Bullet/Ordered List**
: These two commands create and clean up bulleted and ordered lists. They will remove any current list characters at the beginning of each line, compress blank lines in the selection, fix minor indentation mistakes while maintaining the original structure of the list, and properly increment the leading characters of ordered lists. Just select multiple lines and run one of the Services.
: **Suggested key bindings:** Command-Shift-1 (ordered list) and Command-Shift-8 (unordered list)

**Force Line Breaks**
: In Markdown, text without blank lines between it is concatenated into one continuos paragraph, removing line breaks. This is prevented by three spaces at the end of each line, and this Service just adds the spaces to the end of each selected line of text.
: **Suggested key bindings:** None, run it from the Services menu

**Indent/Outdent Selection**
: These Services shift the beginning of all selected lines to the left or right by 4 spaces. Useful for selecting a block of code and indenting it, which makes it get pre/code tags automatically, as well as for manipulating sections of lists to create nested portions.
: **Suggested key bindings:** Command-Shift-] (indent) and Command-Shift-[ (outdent)

**Link List From Clipboard**
: Copy text containing links to the clipboard (in any format, even embedded within other text) and this Service will find all of the links and generate a "reference-style" list of the urls, with titles you can then refer to in your document using `[link text][title]` syntax. It creates short titles based on the domain of the url, and adds incrementing numbers to duplicate titles to differentiate. **This Service is only available when no text is selected.**
: **Suggested key bindings:** Control-Option-V, or run it from the Services menu

**Links From Chrome/Safari Tabs**
: These Services will collect all of the tabs in the foreground Safari or Chrome window (respectively), and generate a reference list in the same fashion as Link List From Clipboard. **These Services are only available when no text is selected.**
: **Suggested key bindings:** None, run it from the Services menu

**Link Selection**
: This will surround the selected text with inline link syntax, and if there's a single url in the clipboard, will link it automatically. Otherwise, it will create a shell (`[link text]()`) with an empty parenthesis pair for you to paste a url into.
: **Suggested key bindings:** Command-Shift-L

**Auto-link web search**
: This Service takes the selected text and runs an immediate search for it using Yahoo. The first returned link is inserted with inline link syntax. It works great for unique words (application names, famous people, unusual words). It will often return dictionary or Wikipedia links for such phrases. You can also add words like "wiki" or "definition" to the selected text to improve the results, and then delete the extra words after linking.
: **Suggested key bindings:** Control-Option-L

**Wrap Parenthesis/Square Brackets**
: Simply wraps the selected text in square brackets or parenthesis, which comes in handy more often than you'd think.
: **Suggested key bindings:** Control-Shift-[ (square brackets) and Control-Shift-9 (parenthesis)

**md - Inline Links to References**
: Select an entire Markdown document with inline links (or a mix of inline and reference links) and run this service to have your links replaced with reference style (`[link text][title]`) and the references placed at the end of the document. Existing references will be preserved, and titles for new references will be automatically generated based on the domain name.
: **Suggested key bindings:** None, run it from the Services menu

**MultiMarkdown to HTML**
: Processes the selected text through Markdown and SmartyPants to generate clean, typographically correct HTML. The selected text is replaced with the final HTML, but if you want both you can select it again, copy it (Command-C) and then Undo (Command-Z) to get the original text back. Markdown and SmartyPants are bundled in this Service, so no external installation is required.
: **Suggested key bindings:** None, run it from the Services menu

**HTML to Clipboard**
: This service does the same thin as "MultiMarkdown to HTML," but leaves the selection alone and copies the resulting HTML directly to the clipboard.
: **Suggested key bindings:** Command-Shift-Option-C

### Installation ###

Simply drag the Services you want to use into `~/Library/Services` (where ~ represents your user's home folder). You will have to enable the Services manually in the Keyboard Shortcuts preference pane of System Preferences. Locate them in the list and check the box to the left. You may have to restart running applications to get them to show up. They will become available in the **Application Menu->Services** menu, as well as from the right/Control-click contextual menu, under the Services submenu (Snow Leopard).

For more information, see my article on [installing System Services][1].

#### Customizing key bindings ####

To add keyboard shortcuts to your Services, open System Preferences and choose the Keyboard Shortcuts tab at the top. Sometimes there's a delay when loading this tab as OS X indexes all of the available applications and services. Click on the Services item in the left side of the panel, and then locate your new Service on the right. Note that you can use the checkboxes you see there to enable and disable Services without having to remove them from the Services folder.

![System Preferences - Keyboard Screenshot][2]

Double click in the blank, white area to the right of your Service, as shown with the arrow in the image. When the blank area turns into a text field, press the key combination you want to use to activate the Service. Use a combination of modifier keys (Command, Shift, Control, Option) and a letter or number. If the combination is available (not used by another Service or existing system shortcut), the input field will disappear and be replaced by your new shortcut. If it doesn't do anything, you'll need to try a different combination of keys.

If you see a yellow "warning" triangle next to your Service, it means that there is another Service or Application Shortcut using that key combination, but it let you add it anyway. This can cause odd results, but mostly just results in neither shortcut doing anything if both associated actions are available at any given time. Sometimes, if one action is only available in one place, and the other in another place, it can be useful to have the same shortcut on related actions. If you're not sure what's conflicting, it's safest just to change your shortcut and avoid the warning.

### End note ###

The Markdown Service Tools were created in Perl, Bash and Ruby and made into Services using [ThisService][3]. I've found the Services [created by Automator][4] to be a bit slow, and when you just want to quickly bold some text, that's not ideal. These sometimes lag on the first run, but are quite fast for me after they've been used once.

For more Markdown goodness, check out [nvALT][5] and, if you're a TextMate user, have a look at the [Blogsmith Bundle][6] ([docs][7]). There are a lot of timesaving tricks in there!

[1]: http://wafflesoftware.net/thisservice/
[2]: http://cdn2.brettterpstra.com/wp-content/uploads/2010/09/media_1284781027400.jpg
[3]: http://macosxautomation.com/services/index.html
[4]: http://brettterpstra.com/howto/install-system-service-snow-leopard/
[5]: http://brettterpstra.com/code/notational-velocity-alt/
[6]: http://github.com/ttscoff/blogsmith-tmbundle/
[7]: http://bundle.weblogzinc.com/
