Wednesday, January 7, 2014

local webservers and static html generation

I haven’t always run an httpd on my main local machine, but I’ve been doing it again for the last year or two now, and it feels like a major help. I started by setting up a development copy of display under Apache, then noticed that it was kind of nice to use it for static files. I’m not sure why it’s any better than accessing them via the filesystem, except maybe that localhost/foo is easier to type than file://home/brennen/something/foo, but it has definitely made me better at checking things before I publish them.

(Why Apache? Well, it was easier to re-derive the configuration I needed for p1k3 things under Apache than write it from scratch under nginx, although one of these days I may make the leap anyway. I don’t see any reason Perl FastCGI shouldn’t work under nginx. I also still think Apache has its merits, though most of my domain knowledge has evaporated over the last few years of doing mainly php-fpm under nginx.)

I’ve resisted the static blog engine thing for a long time now, but lately my favorite way to write things is a super-minimal Makefile, some files in Markdown, and a little bit of Perl wrapping Text::Markdown::Discount. I haven’t yet consolidated all these tools into a single generically reusable piece of software, but it would probably be easy enough, and I’ll probably go for it when I start a third book using this approach.

I’d like to be able to define something like a standard book/ dir that would be to a given text what .git/ is to the working copy of a repo. I suppose you wouldn’t need much.

book/
  authors
  title
  description
  license
  toc

toc would just be an ordered list of files to include as “chapters” from the root of the project. You’d just organize it however you liked and optionally use commands like

book add chapter/index.md after other_chapter/index.md
book move chapter/index.md before other_chapter/index.md

to manage it, though really a text editor should be enough. (Maybe I’m overthinking this. Maybe there should just be a directory full of chapters sorted numerically on leading digits or something, but I’ve liked being able to reorder things in an explicit list.)

I should add a feature to Display.pm for outputting all of its content statically.