I've tried a few different set-ups in the past--Flask and Django in particular--but I think I've finally found something that will work for me: Pelican. It's a pretty neat system--write Markdown (link) with included metadata (date, tags, etc.) and Pelican automatically generates static HTML pages. Combined with simple hosting on Github Pages, and it's a pretty easy way to get going on a personal website.
I've spent the past week or so trying to get everything tweaked to my satisfaction, and I imagine that there will be more tweaking to come. Some of the things that I've changed from the default Pelican set-up:
- Added the markdown extension
- Customized the code-highlighting stylesheets
- Customized the site theme / templates
- Added an SVG image & styling
Adding the Markdown extension
Pelican comes built-in with reStructuredText (.rst) support, which is pretty popular within the Python community for writing documentation. I personally prefer Markdown's simplicity and focus on readability. Adding markdown was as simple as pip install markdown. I also created a template.md file that has the standard Pelican metadata. At some point, I may create a little shell script to automate creating a new post, but it takes only a few seconds to do it by hand.
Customizing the code highlighting
Pelican supports code syntax highlighting using Pygments. It wasn't immediately clear from the Pelican documentation how to set up Pygments with Markdown, but it's pretty straightforward.
In my pelicanconf.py file, I added
| MD_EXTENSIONS = ['codehilite(linenums = True)']
|
This instructs Markdown to use the codehilite extension, and turns on line numbers for all code blocks.
I also followed the very helpful instructions at Kevin Yap's blog here to customize the styling--it looks a little more like code blocks on Github.
Customizing the Site Theme
This took by far the most time, mostly because I'm a CSS newbie.
There are a number of themes available via pelican-themes. I started with the SoMA theme, then hacked at the base.html template and main.css file until I liked what I saw. I changed the background (it might look familiar to spreadsheet jockeys), merged the banner and sidebar into one item, and customized some of the fonts. Eventually, I'd like to convert the CSS files into SASS, so I can better control constants throughout the site style.
Adding the SVG image
The SoMA theme that I started with was created by Launchyard, and it included some of their branding. I decided to add an image of my own using SVG.
I chose SVG over other formats (e.g. PNG, JPG) because it scales well and because it's easy to add styling to via CSS. I'm able to use one rocket.svg image file, and use CSS selectors to hide the buttons and change the colors of the fins.
One thing that I discovered during this process is that you can't use CSS to style SVGs that are embedded via ![]()
tags, only SVGs that are inlined into the HTML DOM itself. Fortunately, there's an easy solution using Pelican!
- Move the image.svg file from the
./static/images/ folder into the ./templates/ folder.
- In the templates, replace any
<img src='/static/images/image.svg'> with {% include 'image.svg' %}.
That's it! Now, the images are inlined directly into the HTML, both allowing CSS-styling and reducing the number of HTTP requests needed to fetch the page.
I also added some CSS transitions when you hover over the SVG image, which is a nice little touch that is really easy with SVG & CSS, but would be more difficult with JS. (I'm even more of a JS newbie.)
This site is still a work-in-progress, but it's a pretty solid start. Hopefully I'll be able to strengthen my HTML/CSS/JS and design chops as I continue to write. No better way than to learn by doing, right?