How it works
Installation
First, grab it from GitHub (be warned, this is alpha software but it isn’t likely to break anything). Right now there’s a lot of presentation markup that was meant for the purposes I was building it for at work. That stuff can be ignored. The bulk of the project, which is actually only a handful of files, is in theadmin and tests folders. The
entire “blog engine” is meant to be self contained and just dropped into
your web root. Now, if you don’t want a URL like mydomain.com/blog then
you should just be able to rip out the contents of the animal-f folder and place it the web root.Usage
To write posts you log into the admin area which, predictably, is at/admin.
Once there you give your post a title, content, then you have to
manually create an excerpt. This can and will be automated in future
versions but, like I said, I whipped this up in a couple of hours
yesterday for a very specific use-case. So stay tuned for big
improvements to that. Categories are one thing I can think need to be
added just off the top of my head now.Once you press the ‘Post’ button, that’s when the magic happens. The very short but powerful
new_post.php script runs. It takes your form input and creates for you:- A valid Unix filename suitable for servers to serve upon request
- An entry on the ‘Recent Posts’ sidebar for you
- Adds an entry to the blog index page with the title, excerpt, and link to read more (I just realized now it adds them in the wrong order)
- Shows you a little heart and a success message so you know it worked
- Creates the actual single post page while the rest of the script adds links in all the right places to it
Files and their usage
So because I made this for a specific purpose and have yet to turn this into a general purpose blogging engine, there are a few gotchas that might trip people up. Here’s what you need to know about Animal./tests folder
After uploading Animal to your server, run the tests first. It’ll save you tons of time later in case there’s a problem. Before using Animal go to/tests/write.php. Enter a string of text and
submit. You should get a success message and a link to the saved file.
If the file contains the text you submitted then Animal should have no
problems working in your environment. If you get an error then you most
likely either have a permissions problem, a PHP version problem, or have
certain features of PHP turned off. If you get an error, start by
giving full permissions 777 to the folder Animal is in and
its sub-folders. Most of the time the problems that arise are from the
PHP user who runs as either nobody, www-data or apache doesn’t have permissions to modify files so chmod-ding the folders to 777
should help. If not then you might be in a locked down PHP environment
(shared hosts, I’m looking at you). If you have access to a PHP.ini file
then use it. Otherwise call support.If you navigate to
/test/env.php you’ll see your PHP configuration. This file just calls phpinfo() and is just a small convenience to help you resolve issues if you have them.new_posts.php
This file absolutely should be modified… in the right places. The first and last part of this file are necessary for Animal to work properly. The middle section should be modified to hold your own custom single page blog post template. It’s important to note that any PHP that you add to the middle template section of this file will be processed and then written as HTML. So, for example, if you have a PHP include statement that pulls in a static header, Animal will run that PHP first and then write the result of that PHP statement to an HTML file. This means that you need to make sure that any PHP within your template is written relative to the path of new_post.php and not relative to where the file will be output. If any PHP errors pop up whilenew_post.php
runs, the output of those errors will be written to the resulting HTML
file exactly as you would have seen them on a dynamic PHP page. This is
because new_post.php uses the output buffer to first run
any PHP statements in the template, hold the results in memory, then
write the output to an HTML file./includes folder
This is where I currently have the blog sidebar and blog index pages. These will change soon and more will likely be added. The basic idea is that these are files that get added on to and appear where static information usually appears on a blog. Its a lot like the custom asides in Ocopress and they’ll resemble them more as I refine this project and broaden it.Markdown
Animal uses Markdown instead of that TinyMCE bullshit. ‘Nuff said.Roadmap
I would consider Animal an alpha release. Let’s call it version 0.1 alpha. Tomorrow I’m attending a hackathonish meetup in Chicago and I’m thinking of using my time there to work on Animal. No matter what I’ll be updating this project and making it far more user friendly in the coming days.That’s how open source projects are born sometimes. Out of someone’s need that turns into a fun project. It wasn’t until I was pretty far into it that I fell in love with the idea and decided to make it awesome. I have a website that I’m going to use this on soon. This is the perfect piece of software for it.
from http://billpatrianakos.me/blog/2012/11/01/introducing-animal-a-static-site-generator-for-php/