Categories
Tools Writing

Markdown for Writing Projects

I use Markdown for writing because it's simple, vendor neutral, and easy to process. Using Markdown, I'm not locked into a particular word processor or proprietary format. I work with text and text is awesome. I want to describe how I use Markdown to write and generate artifacts such as html, pdf, and various e-book formats like ePub.

The writing solution I wanted had these requirements:

  • I want to edit in plain-text, Markdown
  • I want to control how the HTML looks  by writing the CSS myself
  • I want the PDF to look like the HTML
  • I want the e-book format to look like the HTML and PDF
  • I want the HTML, PDF, and e-book formats to be built from the Markdown source, automatically
  • I want to edit remotely on my iPad and have my local and remote work synchronized
  • I want to retrieve past revisions in case I paint myself into a corner and I need to get back to the place I was before

I'll write a few posts over the course of the next few weeks that will serve as a general introduction to how I used MultiMarkdown, make, git, and Dropbox to address these requirements. For now, let's talk about Markdown.

Why Markdown?

Most people I know are already well versed in the beauty of markdown and plain text editing. Markdown is used all over the place. Github uses their own flavor to power all of their README's, messages, comments, and more. There is blogging software that uses it. Lots of editors can do some basic coloring and bolding of markdown text to make it look pretty without a full conversion to HTML markup. It's also just nice to read as plain text, since being readable as plain text is one of the primary features of Markdown.

You may ask what software is available to convert the plain-text markdown into something fancier. There are tons of options here. Here are just few:

  • Jekyll - Takes markdown files and can generate a static website, like a blog
  • Marked - A Markdown editor with HTML preview and PDF generation capabilities
  • Scrivener - A full-fledged writers tool that uses Markdown, manages characters, to-dos, scenes, etc.
  • Byword - A simple iPhone/iPad/Mac editor
  • TextMate - An awesome text editor for the Mac. Unlike vim, easily allows wrapping margins.

Oh how I wish WordPress would allow me to use Markdown as the native editor format! There is wp-markdown plugin, but I haven't had the guts to try it out yet. I'm so afraid of being disappointed. It works by taking Markdown and converting it to WordPress HTML and it converts it back to Markdown when you edit a post. That scares the crap out of me.

Most of the software options listed previously allow you to write in Markdown and they can convert to something like HTML or a PDF with some canned stylesheets. And they probably do this through the GUI. For my purposes, I wanted to use TextMate and I wanted to write the stylesheet myself. I originally tried to use vim as my Markdown editor, but I found out that Vim sucks noodles at Markdown editing.

I didn't want to use a complex tool that has a lot of features. Scrivener might be nice, I never tried it, but it looks awfully complex. I didn't want to use a GUI. I didn't want to pull down a menu to generate my HTML. I wanted to use the command line because the command-line is awesome. In a nutshell, I wanted Markdown to be my code and I wanted a build system that produced my programs: the HTML, PDF, and e-book formats.

I wanted to us make to see that my Markdown files are modified and have my HTML generated automatically. I wanted to write chapters as individual Markdown files and have them auto-magically aggregated into a book a post-process. Just like a linker!

In my next post, I'll talk about MultiMarkdown and why it's awesome and how I use it to generate HTML with my own CSS. I even tricked the HTML generation to insert javascript to produce automatic hyphenation since hyphenation is still something that HTML5/CSS3 don't seem to do well in most browsers I tried.

ッ

Categories
Tools

Private git repos

So I began setting up some private git repos on my own web server. Lots of folks would say to use github for that, or bitbucket. The repos need to be private, mainly because they are my writing projects and works in progress. As you probably know github charges for private repos. Butbucket offers them for free, but I still chose to store these on my own server. Mainly because there will be zero collaboration on these writing projects and github and bitbucket are awesome at collaboration around repos. If it were code, and I'd want people to fork and stuff, things would be different.

To do this, I use a script I put together from forgotten sources on the internet (sorry). The script is written in bash and I run this on my remote host, which I have access to via ssh. Here is the script:

[code lang="python"]
newgit()
{
if [ -z $1 ]; then
echo "usage: $FUNCNAME project-name.git"
else
gitdir="/home/$USER/repos/$1"
mkdir $gitdir
pushd $gitdir
git --bare init
git --bare update-server-info
touch git-daemon-export-ok
popd
fi
}
[/code]

The key to this is the git --bare init and git --bare update-server-info. The --bare option makes sure that the root of the repo looks like what you would normally see in the .git directory at the root of every repo. It doesn't contain the current branch's files like a normal git repo does. This is the ideal way to configure a remote origin you use as the central repo (if your git workflow cares about a central repo).

Once that's created, I installed my ssh keys under a new user I created on my remote server, called gitsrc. On my Mac, I configured an ssh alias via .ssh/config as follows:

[code lang="bash"]
Host gitsrc
HostName primordia.com
User gitsrc
IdentityFile ~/.ssh/id_rsa_disven
[/code]

This allows me to ssh via a simpler syntax. Instead of saying ssh -i ~/.ssh/id_rsa_disven gitsrc@primordia.com, I can simply say ssh gitsrc.

On my local machine, I navigated to the root of each writing project and issued the standard git initialization commands:

[code lang="bash"]
git init
git add .
git commit -m "Initial commit"
[/code]

Then I added the remote origin:

[code lang="bash"]
git remote add origin gitsrc:repos/test.git
[/code]

I could also have been more verbose and said gitsrc@primordia.com:repos/test.git, but the config file allows me to be more succinct so that's what I did.

That's all I have for you.

ッ

Categories
Tools

VIM and tabs and simplicity

I use vim at work for all of my coding. I recently tried to abandon NERDtree in favor of CtrlP, coaxed by a co-worker who did the same. This is an abandonment of a directory tree to find my files in favor of using fuzzy search to find the filename. After I made this switch, I felt like I needed tabs. They didn't seem necessary when I had a directory tree there, but now I feel like I need the tabs so I can switch back for forth between files more easily. I guess I didn't mind clicking multiple times, but I mind typing file names multiple times.

I also program mostly in grails these days, developing a web application that monitors some of our services. In grails, filenames are named in a very specific way so repeat file names are not common. Therefore, the default tab name in vim, whose path is cleverly compressed, is still too verbose for me. E.g.:

[code lang="plain"]
" Tab formatting
" http://vimdoc.sourceforge.net/htmldoc/tabpage.html#setting-tabline
function MyTabLabel(n)
let buflist = tabpagebuflist(a:n)
let winnr = tabpagewinnr(a:n)
let file = bufname(buflist[winnr - 1])
return fnamemodify(file, ':p:t')
endfunction

function MyTabLine()
let s = ''
for i in range(tabpagenr('$'))
" select the highlighting

if i + 1 == tabpagenr()
let s .= '%#TabLineSel#'
else
let s .= '%#TabLine#'
endif

" set the tab page number (for mouse clicks)
let s .= '%' . (i + 1) . 'T'

" the label is made by MyTabLabel()
let s .= ' %{MyTabLabel(' . (i + 1) . ')} '
endfor

" after the last tab fill with TabLineFill and reset tab page nr
let s .= '%#TabLineFill#%T'

" right-align the label to close the current tab page
if tabpagenr('$') > 1
let s .= '%=%#TabLine#%999Xclose'
endif

return s
endfunction

:set tabline=%!MyTabLine()
[/code]

I found most of that in the docs, but this line I wrote to just pull the base filename:

[code lang="php"]
let file = bufname(buflist[winnr - 1])
return fnamemodify(file, ':p:t')
[/code]

I wish there were a simpler solution, but for now this works.

ッ

Categories
Tools

vim and markdown editing

I struggled with vim a bit tonight. I wanted to set it up to edit markdown files and have it behave like a word processor, where at a certain point on a line the text would automatically wrap. After googling for, well, hours, I found out that vim is not a word processor and word wrap simply isn't in its genes.

Well, kind of.

The first thing I did was install the markdown file type plugin. There are a few and I think I like this one the best: https://github.com/tpope/vim-markdown. Not sure why, it just seems to do the most stuff.

Then I set a few options in .vimrc, specific to markdown filetypes:

[sourcecode language="plain"]
autocmd Filetype markdown setlocal wrap
autocmd Filetype markdown setlocal linebreak
autocmd Filetype markdown setlocal nolist
autocmd Filetype markdown setlocal columns=80
[/sourcecode]

The columns=80 actually sets the width of the vim application to 80 columns, which sets he size of the terminal window to 80-columns on my Mac's iTerm. This is a bit annoying. What I really wanted was for vim to be wide, like the terminal, but for the text to wrap at 80 characters.

Meh.

Alternatively, if I could live with line breaks, I could set up vim so hitting gq would force a paragraph to wordwrap, or gggqG to format the entire document. That config looks like this:

[sourcecode language="plain"]
autocmd Filetype markdown setlocal tw=80
autocmd Filetype markdown setlocal wm=4
autocmd Filetype markdown setlocal fo=cat
[/sourcecode]

But I can't live with line breaks. This markdown editing is what I do all of my writing in..., it's simple. I can strip it out if necessary, or I could go the other way and generate html, pdf's, etc. More on that in another post.

ッ