misc-notes.org

miscellaneous notes

• Time-stamp: <2018-11-06 09:10:57 tamara>

Just some notes on making this repo

Converting markdown to org

Pandoc does an excellent job of converting regular markdown to org mode. It needs a bit of help afterwards when converting Jekyll posts, however.

Conversion utility:

pandoc --standalone --highlight=zenburn --wrap=none -f markdown -t org <SOURCE >TARGET

# or simply

pandoc -s --highlight=zenburn --wrap=none -o post_file.org post_file.markdown

pandoc is smart enough to figure out the source and target formats from the file extensions.

Fixing frontmatter

Pandoc sucks at pulling over the Jekyll frontmatter, so that has to be dealt with manually.

A typical bit of frontmatter:

---
layout: post
title: "Delete a remote git branch"
date: 2013-10-05 08:03
categories: [git]
tags: [remote, branch, remove]
source: http://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide/5977604#5977604
---

• the title: yaml key is used in the org file with the first headline

* Delete a remote git branch

The other frontmatter is just becoming a plain list:

- Time-stamp: <>
- original date: 2013-10-05 08:03
- keywords: git, remote, branch, remove
- source: http://stackoverflow.com/questions/315911/git-for-beginners-the-definitive-practical-guide/5977604#5977604

The time stamp thingie, <> gets filled in by Emacs when the file is saved, giving the last time the file was edited and saved. Keywords are the former categories and tags from the Jekyll post.

Fixing code listings

This is the most different for pandoc since Jekyll uses a Liquid tag highlight to format code listings. It also uses the standard Github-flavoured Markdown [GFM] code-fence, which at least pandoc tries to make work.

Org mode in emacs, however, has a really spiffy way to put in code examples. If you type <s and then hit TAB is expands to a #+BEGIN_SRC/#+END_SRC block, and you can put the language mode at the end of the first #+BEGIN_SRC line:

#+BEGIN_SRC rjsx
  // some javascript code
#+END_SRC

When you drop the cursor into the block, hit C-c ' a separate window opens in the programming mode specified, which is really cool.

I’ve been snagging the code examples out of the markdown file as is and pasting them in the source editing window after deleting the highlight block from the org version.

Rake tasks

moving org files

When I’ve completed converting a markdown post to an org file, I’m removing the markdown file and putting the org file in a subdirectory based on it’s year and month, and removing the date string from the front of the post file name. I wrote a rake task to do this: move_posts.

rake move_posts

creating index files

I wrote another rake task that builds an index.org file of the posts in that directory. I didn’t bother with an index file for the monthly “leaf” directories since they’re all there already. These index.org files have no appreciable formatting, just the link to the file. I may make those better over time, we’ll see. :D

rake build_indexes

Note: I am planning on keeping a Gemfile and package.json file out of this repo, just have it be the posts. Just have to remember to have rake installed globally.

creating the atom feed

It’s necessary for communicating when new posts drop. The atom feed is at ./docs/feed.xml, which is set up for Github pages. (There’s an index.html file there as well telling folks where to find the content).

rake mkfeed

conclusion ?

Somehow, this still feels like too much work, but it’s still better than it was. It might be that I’m still putting finishing touches on it, it might be that I’m never satisfied and have to tinker. At any rate, we’ll see what happens.