1. Ted Lilley
  2. clip-pandoc

Overview

HTTPS SSH

Clip-pandoc

I made a command for Notepad++ to convert between HTML, Markdown and Textile. For me, it's useful in four cases:

  • When I want to write material from scratch
  • When I want to polish or simplify existing content from HTML
  • When I want to work on Textile documents
  • When I want to lift material from other documents or email

Before I go into those details, I'll tell you how to install it and use it, which is pretty simple.

License

Clip-pandoc is released under an unmodified Apache 2.0 license, which is available in the root directory of the source and the redistributable as the file LICENSE.txt. You can familiarize yourself with the terms of the license via the Apache website's description.

In all cases the copy of the license which is included in the source distribution, available from http://bitbucket.org/lilleyt/clip-pandoc, is authoritative and binding.

Installation

I'm going to call notepad++ just "notepad" so it's easier to type.

First, make sure you've got notepad installed (it is, right?). Then, make sure it isn't running.

You'll need to install pandoc 1.8 first. Make sure you check "Add application directory to your path" in the final dialog.

Then install clip-pandoc. Defaults are fine.

You'll need to log off and log back on so the path change takes effect. You don't need to reboot, just logging off and on is fine.

Test it

Open notepad.

To test it out, copy any text into notepad. Get at least a couple paragraphs.

Notepad has a "Run" menu. Near the bottom you should have a "Markdown to HTML" entry. Select it.

A dialog will pop up that asks you to select your text. Use the mouse to highlight the text in notepad, then click OK.

After a moment, the text should be replaced with the HTML version. If you see paragraphs with <p> tags, you're good. Note that Pandoc's HTML looks a bit funny because of dangling >'s.

If it doesn't work, let me know. A good place is in the forums.

Other stuff

Now that it's been tested, I'll explain the other Run menu entries. There are ones to go back and forth between HTML, Markdown and Textile.

You can get HTML out of any site on the web by right-clicking the page and selecting "View Source", but it can be tricky locating the content you wanted when it switches to the source view. I recommend using Google Chrome with the View Selection Source extension to make this easier.

As for Markdown, I use it for writing in general a lot of the time now. Here's a good reference for starting with Markdown.

On a sidenote, there's one other menu entry in notepad that you may notice which says "HTML to Markdown (strict)". This is because pandoc enhances basic Markdown with a few tricks of its own, such as letting you make HTML tables easily.

Those tricks are useful, so I like pandoc, but sometimes you need Markdown that doesn't allow the extra tricks in order to be compatible with other websites. Strict tells it not to use those extras.

What I use it for

When I want to write material from scratch ~ I use it to draft content for two reasons: first, it's easier to write with Markdown than to use the wysiwyg editor in mojoPortal. Second, forcing myself to write outside of the web page editor (in notepad) means I rarely lose my work to an accidental button press in the browser.

When I want to polish or simplify existing content from HTML ~ Converting HTML into Markdown removes all of the HTML that corresponds to Markdown's simple formatting, leaving the rest of the HTML intact and easily removable by eye.

When I want to lift material from other documents or email ~ Most email is usable directly as Markdown without changing it at all. In fact Markdown was designed with that in mind. As for formatted material in word, it's usually easier to paste it to text and reformat with Markdown rather than trying to paste directly into a wysiwyg editor because it usually gets somewhat mangled in the translation. Markdown is very predictable while pasting from Word isn't. You can even save Word to HTML, use pandoc to convert to Markdown, edit and convert back to HTML.

Building Clip-pandoc from Source

The repository is hosted at Bitbucket.org.

Clip-pandoc consists of a compiled AutoHotkey script and an Inno Setup installer. It can be built by hand (compile script, compile installer), but for convenience there is a build script as well written in TakeCommand's batch language.

Since Notepad++, AutoHotkey and TakeCommand are all Windows programs, this of course means that this is a Windows-only project.

Prerequisites:

  • TortoiseHg

    The build process relies on a TortoiseHg-specific feature not included in the regular Mercurial client, called commit exclusions. You need to include the following text in your repository's .hg\hgrc file after cloning the repository:

    [tortoisehg]
    ciexclude = src/clip-pandoc.ahk.ini,setup/clip-pandoc.iss
    

    Version as of this writing is 1.1.9.1.

  • Autohotkey Basic

    Basic is all that is required. AutoHotkey_L should work fine too, but I use Basic first because the _L package doesn't include documentation yet.

    Version as of this writing is 1.0.48.05.

  • Compile_AHK II

    Compile_AHK enhances the regular AutoHotkey compiler with the ability to set properties on the resulting executable, among other things. Make sure it's set on your path.

  • Inno Setup

    I recommend going with the QuickStart pack which includes the IDE that provides a wizard to help create install scripts. Add this to your path so the compiler can be called.

    Version as of this writing is 5.4.1.

    Clip-pandoc's installer requires the ModPath Inno Setup script which is already included in the source repository.

  • TakeCommand Console LE

    Back in the day, when DOS ruled the Earth, there was a replacement shell called 4DOS, and it was good.

    Today it lives on as TakeCommand. There is a free version called TakeCommand Console LE, which I have found to be the most straightforward method of creating builds after having tried numerous other build systems.

    It uses an extended, backward-compatible batch language, stored in .btm files. build.btm is my build script, which you can run from within the TCC/LE shell. I've also included a build.cmd script which can be double-clicked from Windows Explorer as well. It just calls the btm script.

  • fart

    Yes, fart, aka Find and Replace Text. This is a super simple sed alternative. Put this somewhere in your path.

Once installed, clip-pandoc requires Notepad++ and Pandoc, of course, but the build process doesn't require either.

Note: As of the current version, if you have any custom entries in your Notepad++ Run menu, the clip-pandoc install will overwrite them. I've not yet started to address the issues list.