Month: February 2013

A Styled HTML Document from Markdown

jiffyclub, Leave a comment

There are many, many command line converters for turning Markdown into HTML, but for the most part these make HTML fragments, not full documents with CSS styling. That’s fine most of the time (e.g. when I’m writing blog posts), but sometimes I want a full, pretty document so I can print it out (typically for presentation notes).

To fill this hole I put together a small script that converts Markdown and wraps the HTML result in a template that includes Bootstrap CSS. I set the fonts to sans-serif and monospace so that they are taken from the defaults for your browser, making it easier to use your favorite fonts.

The script requires the Python libraries Python Markdown, mdx_smartypants (a Python-Markdown extension), and Jinja2.

#!/usr/bin/env python
import argparse
import sys
import jinja2
import markdown
TEMPLATE = """<!DOCTYPE html>
<html>
<head>
<link href="http://netdna.bootstrapcdn.com/twitter-bootstrap/2.3.0/css/bootstrap-combined.min.css&quot; rel="stylesheet">
<style>
body {
font-family: sans-serif;
}
code, pre {
font-family: monospace;
}
h1 code,
h2 code,
h3 code,
h4 code,
h5 code,
h6 code {
font-size: inherit;
}
</style>
</head>
<body>
<div class="container">
{{content}}
</div>
</body>
</html>
"""
def parse_args(args=None):
d = 'Make a complete, styled HTML document from a Markdown file.'
parser = argparse.ArgumentParser(description=d)
parser.add_argument('mdfile', type=argparse.FileType('r'), nargs='?',
default=sys.stdin,
help='File to convert. Defaults to stdin.')
parser.add_argument('-o', '--out', type=argparse.FileType('w'),
default=sys.stdout,
help='Output file name. Defaults to stdout.')
return parser.parse_args(args)
def main(args=None):
args = parse_args(args)
md = args.mdfile.read()
extensions = ['extra', 'smarty']
html = markdown.markdown(md, extensions=extensions, output_format='html5')
doc = jinja2.Template(TEMPLATE).render(content=html)
args.out.write(doc)
if __name__ == '__main__':
sys.exit(main())
view raw markdown_doc hosted with ❤ by GitHub
A Styled HTML Document from Markdown

Approaching git from svn

jiffyclub, , 1 Comment

“Yield and overcome” – Lao Tsu, Tao Te Ching

Over the past year or so I have on a few occasions taught git to people
accustomed to using Subversion. These are experienced software developers so it
seems like it should be easy, but it is almost always a difficult process
filled with acrimony, resistance, and gasps. (And this from people who seem
to use Emacs, vim, and Linux without complaint.)

And yet when I teach git to people who don’t already have a preferred
version control system it seems to go pretty well. It takes time, and there
may be confusion, but we demo and practice and learn as with any topic.
There is no hate. I think I’m beginning to understand the situation:

  1. Git and svn are different.
  2. People do not like their workflow changed.

Git isn’t just a little different, it’s completely different. But, dear
svn users, git is not different because it doesn’t like you. Git is different
because it’s optimized to facilitate the collaboration of a number of
developers working on a rapidly changing code base. Some examples:

  • Branching is easy in git so that you can work in peace isolated from
    upstream changes until you are ready to send your work back.
  • When it’s time to merge back git provides rebase to facilitate cleanly
    integrating upstream changes.
  • Git is distributed so that you and everyone else can make all manner of
    branches and experiments without dirtying up the master repo.

Git is different from svn, but it does well what it is designed to do.
This brings me back to the Lao Tsu quote from the top and a simple message
to svn users learning git: You will have to drop your svn workflow to make
the most of git, but it’s not because git is bad, it’s just different. Yield,
use git in the way it was meant to be used, and be happy.

Approaching git from svn

git: Pushing to a Remote Branch with a Different Name

jiffyclub17 Comments

Normally when I do a push in git I do something like git push origin master, which really means push from the local branch named master to the remote branch named master. If you want to push to a remote branch with a different name than your local branch, separate the local and remote names with a colon:

git push origin local-name:remote-name
git: Pushing to a Remote Branch with a Different Name