Mike's Autojournal 2011-12-18

Mike Shea's Website

Pueblo: Python Markdown Static Blogger

30 second summary

I decided to formalize the script I use to generate this website and my other big website, Sly Flourish and release it to Github. Pueblo is a single python script that generates a blog of static HTML files from a directory full of markdown text files. It's small, fast, easy, secure, and extensible. While it doesn't have many of the features of bigger blog platforms, Pueblo lets you spend less time on website maintenance and more time writing.

A single simple script

Pueblo is a single Python script that, when run, generates HTML files, an index file, an archive file, and an RSS feed from a set of markdown formatted text documents. If you're looking for a more full-featured blogging platform, one where you don't have to mess with the code itself, this isn't for you. Pueblo is primarily built to run my own websites, MikeShea.net and SlyFlourish.com. I wanted to release the code out there in case others could benefit from it or might teach me how to make it better.

HTML generation from Markdown files

At its core, Pueblo uses Markdown files to generate HTML. These Markdown files include a subset of MultiMarkdown metadata to generate page titles, dates, and author links. These markdown files must have a .txt extension, must be in either ASCII or UTF8, and must have the title, author, and date fields in order. You can look at the markdown for this article as an example.

The configuration lets you exclude certain .txt files in case you don't want them.

The generated index.html file uses a stylesheet called "style.css" and another called "iphone.css" for a mobile display. The script also calls a file called "sidebar.html" to display aside content.

The advantages of static HTML generation

There are many advantages to a blog that generates static HTML. For one, you are putting CPU processing time where it belongs, crunching articles when you WRITE them not when your readers READ them. Most blogging platforms store your articles in a structured database. Every time a reader hits your site, it has to reach into that database and generate a page. There are lots of ways to speed up that process but much easier is to simply serve a static web page. This lets the website scale much better than any sort of server-side code execution.

Static HTML means your site will be very very fast.

Archiving your website

The ability to easily archive and transport your site is another big advantage to static HTML generation. If you decide your days running the blog are over but you want to keep the site, you can just copy all the text and HTML files and the site can live anywhere you want to put it. All of the generated URLs in Pueblo are locally referenced so you can even copy it to a thumb drive and still run the site like you would normally.

This means, years from now, you can still see your website as it ran without having to run a huge out-of-date blogging platform to see it.

Security

Static HTML is also inherently secure. Instead of constantly dealing with hackers attempting to find vulnerabilities in your server-executed code, you only serve static HTML. There's no code to hack. The script itself runs only when you run it either with a cronjob or as a single-run CGI script. There are no parameters accepted so you don't need to worry about dealing with bad data getting passed through. Securing the script and your website are still important but it's much easier than having to constantly and continually update your code (I'm looking at you Wordpress).

Few features

The disadvantage to a script like this is the lack of features. There's no comment board, no ping backs, no plugins, no built-in search, no workflow system, and no other advanced blogging features. Again, if these features are important to you, look elsewhere. This script does have two collaborative features. First, it generates a 20 article RSS file called index.xml and second, it lets your readers link articles on Twitter referenced back to your account. It also includes Google Analytics and Amazon referral requests, mainly because I use these on my own sites. Other than that, the features are very slim.

Make it your own

I expect the users of this script to know some Python and thus I expect you to make this script your own. I don't plan on doing a lot of updates or adding a lot of features so you should feel free to edit it as you see fit. A lot of the HTML generation is embedded in the script so you'll need to dig a little deeper to modify the code. That said, I hope you will build this script into the perfect script to run your site.

If you like Pueblo and want to give back, please bookmark and use this Amazon link to throw a few bucks my way while you pick up that copy of Deadwood you've always wanted to buy.

Sly Flourish

2011 Poster Map Buyer's Guide

The Battle Map Comparisons article on this site continues to be a popular draw. We all love our encounter maps and there's a lot of potential options available. The more we use these options, the more we can see the advantages between one and another. Today we'll pick out the best buys for awesome battle maps.

The polycarbonate sheet

The poster-sized polycarbonate sheet, available at Home Depot for about $22, is the best accessory you can buy for poster maps. It's one of those great finds that has so many uses, you keep discovering more as you use it. When placed over a poster map, this polycarbonate sheet protects the map, keeps things perfectly flat, feels great when used with miniatures, and lets you draw on it with a wet or dry erase marker. It works just as well over dungeon tiles and dry-erase maps as it does over pre-printed poster maps. It's the best money you can spend for your encounter setups.

Poster maps

For the money, the most detailed battle maps you can get come from pre-printed poster maps. The best value you're likely to find come from the upcoming Map Packs: Haunted Temples and Vaults of the Underdark, due to come out next year. Each of these packs will contain three double-sided poster maps. That's twelve maps for $18, a deal that is very hard to beat. If you can't wait, however, there are a few great options for poster maps you can get right now including the following:

D&D Starter Set Red box: Includes two versatile poster maps including the Monster Lair / Crossroads and the Inner Dungeons.

Dungeon Master's Kit: Includes four very versatile maps; the roadside shrine / arcane sanctum, the skull cave / tavern and stables, the keep wall, and the road-side farmstead.

Monster Vault Includes the winter village and a detailed dungeon.

Monster Vault 2: Includes the small temple / swamp lair and the cracked cave lair / rocky hillside.

Madness at Gardmore Abbey: Includes the large temple, the entry hall / crypts, the throne room / outer temple, and the tower complex.

These five products contain a total of 21 detailed encounter areas you can use and re-use throughout your campaigns.

The dry-erase battle map

For pure versatility, the fold-up dry-erase Gamemastery Flip Mat is still a great purchase. At about $12, it can let you draw any environment your imagination can dream up. The more detailed you want to be, however, the more work it will take. You're never likely to build out an environment as beautiful as you'll have with poster maps, but it can fill in those gaps that poster maps don't fill. It's always worth having one of these on hand.

What about dungeon tiles?

Over the past five years, I've tried and tried to use dungeon tiles well and never had a lot of luck. While more flexible than poster maps, they take too long to set up and never quite build out the dungeon you want. Unless an adventure specifically calls for them, like the Monster Vault adventure, they aren't generally going to fit the environment of a pre-published adventure. I ended up giving away most of the tiles I have except for a set of the Dungeon Tile Master Sets. Even those I can't really recommend. You're simply better off with a dry-erase flip map and a pile of poster maps.

Where's the Dwarven Forge?

I've talked a lot about Dwarven Forge in the past and have used it for years in my own games. As much as I enjoy it, I cannot recommend its purchase for four simple reasons:

  1. It's too expensive. A single set of Dwarven Forge can pay for nearly all of the other recommendations on this list and two sets of Dwarven Forge isn't enough to build a good battle map layout. A good set of Dwarven Forge can quickly get into four figures.

  2. It's too heavy. Unless you run your D&D games at your own house every week and you have a wife willing to let you keep twenty one plastic shelves in your dining room, Dwarven Forge is simply too heavy to transport.

  3. It takes too long to set up and tear down. It takes just a couple of minutes to set up a battle map. It can take an hour or more to set up a good Dwarven Forge setup. That's time you're taking away from the planning of the rest of your game.

  4. It doesn't lend itself to dynamic gaming. If you and your group like heading in any direction at any given time, Dwarven Forge isn't for you. While you can quickly put together an encounter area using maps, dungeon tiles, or a dry-erase mat; Dwarven Forge just doesn't have that flexibility.

While Dwarven Forge setups are still the best looking set-ups you can have for your D&D game, the four reasons above keep them out of this year's buyer's guide.

If you enjoyed this article and love D&D, take a look at Sly Flourish's Dungeon Master Tips and Running Epic Tier D&D Games. You can also pick up some great miniatures to go with your battle maps by buying some D&D Miniatures from Troll and Toad, an official Sly Flourish sponsor.

Twitter / mshea

Twitter / SlyFlourish

Top Stories - Google News

Dow Jones 30 days +/- %1.5: --.-'--.--.-.-'-'-----.'----- 11866.39

Vienna, Virginia Weather : 29F MOSTLY CLOUDY