Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
JekyllMail enables you to post to your Jekyll / Octopress powered blog by email.
Ruby Shell
branch: images_untrust…

This branch is 1 commit ahead, 6 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
.gitignore
Gemfile
README.md
jekyllmail.rb

README.md

JekyllMail

JekyllMail enables you to post to your Jekyll / Octopress powered blog by email.

How it Works

Once configured (see below) JekyllMail will log into a POP3 account, check for messages with a pre-defined secret in the subject line, convert them into appropriately named files, and save them in your _posts or _drafts directory. After that your normal Jekyll watcher process can take over and do its thing.

Warning: At the end of every run JekyllMail deletes every e-mail in the account. This is for two reasons: 1) we don't want to have to maintain a list of what e-mails we've already ingested and posted 2) once an e-mail's been ingested we don't need it 3) there are probably 400 spam e-mails in the account that should be deleted. 4) less e-mail in the box means faster runs.... ok four reasons.

Usage

The magic is all in the subject line. In order to differentiate your email from the spam that's almost guaranteed to find your account eventually suck in the appropriate metadata A subject line for JekyllMail has two parts the title (of your post) and the metadata which will go into the YAML frontmatter Jekyll needs. The metadata is a series of key value pairs separated by slashes. One of those key value pairs must be "secret" and the secret listed in your configuration. Note that the keys must contain no spaces and be immediately followed by a colon.

<subject> || key: value / key: value / key: value, value, value

An example:

My Awesome Post || secret: more-1337 / tags: awesome, excellent, spectacular

Your secret should be short, easy to remember, easy to type, and very unlikely to show up in an e-mail from another human or spammer.

Your e-mail can be formatted in Markdown, Textile, or HTML.

Subject Metadata

There are a handful of keys that JekyllMail is specifically looking for. All of these are optional except "secret":

  • draft: defaults to false. Set this to "true" if you want this post to be saved in the _drafts folder.
  • markup: can be: html, markdown, md, textile, txt (textile)
  • tags: expects a comma separated list of tags for your post
  • slug: the "slug" for the file-name. E.g. yyyy-mm-dd-slug.extension

Images

Image attachments will be extracted by JekyllMail and placed in dated directory that corresponds with the date of the posting.

For example If you attached flag.jpg to a post sent on July 4th 2012 it would be stored in /2012/07/04/flag.jpg

JekyllMail will look for the image tags in your document that reference the image filename and update them to point to the correct published file path. For example it will convert ![alt text](flag.jpg) in a Markdown document to ![alt text](http://path/to/images/dir/2012/07/04/flag.jpg). Textile and HTML posts are also supported.

In pracitce this simply means that if you insert a ![alt text](flag.jpg) tag and attach an image named flag.jpg to the same email everything will show up as expected in your post even though JekyllMail has moved that image off to a dated subdirectory (just like the post).

Configuration

If you're using Jekyll you're using git. JekyllMail is configured via its own section of you global git config.

[jekyllmail]
    postsDir = /path/to/my\_jekyll\_site/source/_posts
    draftsDir = /path/to/my\_jekyll\_site/source/_drafts
    imagesDir = /path/to/my\_jekyll_site/images
    popServer = mail.example.com
    popPassword = 1x2x3fdc3
    popUser = jekyllmail@example.com
    secret = easy-to-remember-hard-to-guess
    defaultMarkup = markdown
    siteUrl = http://www.example.com

You can add these to your ~/.gitconfig by editing it directly or by commands like the following:

git config --global add jekyllmail.postsDir /path/to/my_jekyll_site/source/_posts

Please note that paths and urls must not end with a slash. Also, JekyllMail assumes that your images directory lives directly under your siteUrl. E.g. http://www.example.com/images

Your popUser doesn't have to be an e-mail address. It might just be "jekyllmail", or whatever username you've chosen for the e-mail account. It all depends on how your mail server is configured.

Known Issues

Check out the Issues page on Github for the current list of known issues.

Credit where credit is due

JekyllMail was based on a post & gist by Ted Kulp. JekyllMail expands upon his original idea, adding POP3, spam resistance, and image handling. It should work on any OS X or Linux system.

License

JekyllMail is distributed under the MIT License.

Something went wrong with that request. Please try again.