spod.cx

Meek README

What is Meek?

Meek is a simple website 'content management system'. I wrote Meek to manage my website in January 2006 - html files are a nuisance to edit and I wanted something I could update from anywhere with nothing more than an ssh session.

Meek uses a human friendly text-based format called Markdown to generate its pages. In addition to turning these simple text files into html, it can also maintain an RSS feed, blog-style pages, a sitemap and 'recently updated' pages lists. The files Meek produces are simple static HTML, so you don't need any clever software to serve them, and they won't heavily impact your webserver.

Meek is licensed under the GPL v2.

The latest version of Meek can be found at http://spod.cx/meek/

Using Meek

In the Meek tarball is effectively all you need to create a basic website:

To use meek you'll need to edit the meek.pl script and change some of the default values at the top. At the very least you'll want to edit $baseurl and the RSS descriptions. Once you've done that, you can simply run ./meek.pl to generate the html for your site. By default meek creates files with a .shtml extension. This is a personal preference and can be easily changed by editing the script.

Regular Pages

To create a new page using your favourite editor, simply create a new file with a .page extension.

Meek pages follow an RFC822 style format:

title: Page title
comment: This is a page
ignore: yes

Actual page content starts here.

The section at the top is interpreted as headers that you can use later on. I only make use of two of these - 'title' which unsurprisingly defines the page title and 'ignore', which prevents a page (or directory in an index.page) from showing up in a sitemap or other autogenerated list. You can have as many of these as you like - they'll be ignored unless you explicitly make use of them. The headers are case sensitive.

Anything after the extra new line is interpreted as actual page content and will automatically be converted from Markdown into HTML. You can use raw HTML within Markdown, so if you need to do something within a Meek page that Markdown doesn't support, you can always fall back to plain HTML for just that part.

Once your page is complete, rerun the meek script (./meek.pl) to generate an HTML page from it.

Extra goodies

Meek will automatically generate an RSS feed for your pages (by default called feed.xml in your site root) containing a link to recently updated pages. It doesn't include any content from the pages.

Meek makes use of filesystem timestamps to determine if a page has changed. This does mean you need to be careful how you edit your site in case you accidentally republish pages, but most sane text editors shouldn't cause any problems.

If you need to do a sneaky edit (fixing a typo for example) without changing the recently updated lists or RSS feed then you can use the 'medit' script. By default this uses vim as the editor.

You can also have multiple .header and .footer files. Meek will apply the 'closest' ones to any given page, so if you wish to have a different header and footer for a particular directory of your site, simply create a .header and .footer in there, and Meek will pick those up for that directory and any below it.

The lj2meek.pl script will take an ljArchive XML export and turn it into Meek compatible files (with the correct timestamps) if you wish to migrate from LiveJournal to Meek.

Special Markup

Meek has a few special commands which are enclosed in a double percent 'tag': %%command:arg%%

buildlatestlist

%%buildlatestlist:20 .%%

This simply builds a list of last edited files - newest at the top, and including the time the file changed. The first argument is the number of items to display - 0 means unlimited (used in the blog archive for example) and the second is the directory to apply this to. '.' in this case means the directory that file lives in.

buildblog

%%buildblog:10 .%%

Buildblog creates a page which includes content from the recently edited pages it finds sorted as newest first. The title of the pages is inserted as an 'h2' HTML tag, and the date the files were edited is added. Again, the first argument is number of pages to show and the second is the directory to get them from.

buildtree

%%buildtree:.%%

Buildtree is used to create a complete list of 'pages'. In the example pages I use it to generate the sitemap. I also use this to create the recipes recipes page on my website.

ins

%%ins:title%%

Ins takes the magic headers from each individual page and does a simple search and replace. This isn't all that useful for regular pages, but it can be used to customise the content of the .header and .footer file for each individual page. I use it mostly for putting a per-page title into the header.


Contact: site@spod.cx