Simple PHP-powered static blog generator.
PHP JavaScript CSS
Latest commit d578a39 Jul 23, 2014 @cesarparent CriticMarkup support in drafts previw
CriticMarkup can now be used in the web interface editor. it will be
rendered in draft previews, and can be left, as it will be stripped
from the published post.

Fix: Plus signs in body copy are now transmitted properly

readme.md

Asteroid

A simple php-powered, Markdown static blog engine.


Overview

Asteroid's Default Blog

Asteroid is an engine that generate static-HTML blogs, based on a template, and using Markdown plain-text files as data. That means that no databases requests are done when a visitor loads a web page. It's fast.

Oh, and it also means you don’t have to use one of those “amazing” online editor. Just type in your favourite markdown editor.

Above all, keep in mind that asteroid is nowhere near a finished! much less universal engine. I made it to suit my needs, my workflow, and it might very well not stable at all.

Requirements

Asteroid was tested properly on PHP 5.3 onwards, and very quickly on PHP 5.1 and 5.2. You obviously need a server running PHP, and also allowing .htaccess files (for the API to work).

Installation

Edit the _api/options.yaml and _api/index.php files to set your blogs parameters (timeline, name, author…). Change the default template (the files we located in assets/template) until you love your blog’s design.

Then upload the whole directory to your server. Once uploaded, you have to load at least once http://your-blog.com/publish, to generate your blog’s HTML files. And then you’re good to go!

Usage

Asteroid can be used in two ways:

Manual files handling

Asteroid stores all the content in the _content/ directory. To relate a new post, create a .md or .txt file in the post directory. The file name should follow the pattern yyyy-mm-dd-your-post.txt, for example 2013-11-23-doctor-who-is-fifty.txt.

The post’s metadata is defined in the first few lines of the file, using a basic syntax:

title: "Doctor Who is fifty"
author: "Paul McGann"
tags: TV, Sci-fi

Some great content here (you can format it in markdown)

Once you are happy with your post, load the http://your-blog.com/publish In your browser, wait for the engine to run through everything, and share your great writing! Posts are published at urls of the type /yyyy/mm/your-post/(index.html). The example post, for example, would have been /2013/11/doctor-who-is-fifty/.

Static pages work the same way, except the file names should not include the date bit at the beginning. They are published to the root of your blog, like /about-this-blog/.

HTTP api

Asteroid also comes with a HTTP api, allowing you to create apps that connect to Asteroid blogs to edit and create content. The full documentation has its own GitHub repo (still unfinished).

The api was loosely designed after the Tumblr API, which I find interesting and not too complicated. Thanks to Marco Arment for that!


Template files.

Templates are plain php files. The content is HTML, with some php calls in it to access the exposed variables. The filenames are self descriptive: header.php and footer.php are included at the beginning and the end of each page. index.php contains the structure of one item of the front page, post.php and page.php are more or less the same, but for individual posts and pages. archive.php will be used for each archive entry. You shouldn't have to edit the rss and site map templates.

Asteroid comes with a sample template. It's more or less responsive, and should give you an idea of the way templates are done. Use it if you want, but my poor design skills might entice you to roll your own!

a list of all variables you can access in templates is available in the documentation, and here as a cheat sheet.

Acknowledgments

The first version of Asteroid was heavily inspired by Steven Frank's Laguna engine. It's also obviously inspired by Jekyll, since the first version's goal was to handle my Jekyll blog with the less possible modifications.

Asteroid relies on PHP Markdown Extra and PHP SmartyPants, by Michel Fortin, and Spyc YAML parser.

PHP Markdown Extra

PHP Markdown Lib Copyright © 2004-2013 Michel Fortin http://michelf.ca/ All rights reserved.

Based on Markdown Copyright © 2003-2005 John Gruber http://daringfireball.net/ All rights reserved.

PHP SmartyPants

Copyright (c) 2004-2013 Michel Fortin All rights reserved. Based on SmartyPants Copyright (c) 2003-2004 John Gruber All rights reserved.

License

Asteroid is released under the MIT license. You can read the full license in the LICENSE file, but it basically means that you can use, edit, and redistribute Asteroid however you want, as long as you keep the copyright files and the attribution at the beginning of the files. Share!