Gitpress -- Blissful blogging for hackers

Gitpress transforms this

/
+- 2011/
|    +- 01-init.md
+- 2012/
|    +- 01-welcome-to-gitpress.md
|    +- 02-tips-for-gitpress.md
+- README.md

into a living, breathing website.

What?

Gitpress is a collection of tools for working with presentation-less blog repositories. Your layout and theme can be customized independently, effectively separating your content and presentation concerns.

Gitpress also takes full advantage of git. There's no roles, timestamps, or authors mixed in with your content by default. This metadata is all inferred.

Why?

How many times have you put off writing because you couldn't settle on a CMS? Or wanted to switch services, but felt overwhelmed by the amount of work involved? Have you ever been inspired to write but then wasted it on setting up the blog? Gitpress is here to help.

For new blogs

Write first. Git-push for review and comments. Iterate your story based on real feedback. All before you publish. As a bonus, it's much easier to customize the style of your site when you have some content to work with.

For collaboration

With the power of a distributed version control system, you can host your content like any other project and allow your words to evolve socially. Pull in corrections, site improvements, or even outsource or fork a front-end completely as you write, without bottleneck.

For the future

Gitpress was created with the belief that your content and your presentation shouldn't mingle. By decoupling these layers, you're no longer locked into a single host, particular blogging platform, or even how you organize your files. Through any change, you can still keep your focus on what's most important since day one. Your writing.

Getting Started: Writing

You'll begin like you would any other programming project:

$ mkdir myblog
$ cd myblog
$ git init

You should also create a README.md file if you're feeling generous, indicating this repository contains the content of your blog.

Now you can begin writing. Create a new Markdown file for each blog post. Commit normally. Push to publish. The only requirement is that you prefix any files or directories that you want shown in a particular order with a number. You may want a directory for each year:

/
+- 2012
    +- 01-my-first-post.md

That way you don't end up with too many files in one place as your story unfolds.

File conventions

File organization is extremely flexible. The rules are:

1. Files and directories beginning with a letter are named
2. Files and directories containing numbers without letters are indexed
3. Files and directories beginning with a number, containing letters are ordered named

The special characters !@#$%^&()_-+=,.[]{}' are allowed and are ignored by the above. The rules are sensible for blogging and are used in the lookup process described in the next section.

For example:

/
+- 2012
|    +- 01-first.md
|    +- 02-second.md
+- README.md

Daily writers may prefer:

/
+- 2012
|    +- 10
|    |   +- 01-my-first-post.md
|    |   +- 20-another-in-october.md
|    +- 11
|        +- 01-movember-has-arrived.md
|        +- 11-growing-a-moustache.md
|        +- 18-wheres-my-moustache.md
|        +- 28-moustache-finally-arrived.md
+- README.md

What's important is that you are comfortable with your files. There's no need to get hung up over this. Start with something simple. Reorganize later, moving your posts into month-based sub-directories. And you can do this without making a mess of your permalinks, since that's all handled by your presentation layer.

Next Steps: Presenting

Now that you have a simple repository containing some amazing content, it's time to get your work out there. There's a few options.

Deploy with Git

Simply push your work to an existing Gitpress server:

$ git push mysite

The command-line interface

Install Gitpress using pip:

$ pip install gitpress

You can preview your working directory without committing anything:

$ gitpress preview
 * Running on http://localhost:5000/

This uses the default presentation configuration by default. Locate the admin page from there to change the layout and theme.

Setting up a Gitpress Server

There's no command-line interface to fully serve a Gitpress website. Instead, you'll need to create a small Python web script that imports Gitpress. This allows server projects to include their own dependencies and optimizations. You can also override the functionality of any of the components as needed.

Push-based

Note: this feature is being designed, planned for a future release.

The simplest thing to do is let Gitpress listen for a push and handle the rest:

import gitpress

if __name__ == '__main__':
    gitpress.run(port=8080)

Save the above to a file called server.py and run it:

$ python server.py
 * Running on http://localhost:8080/

To see your blog in action, Git-push to localhost. For example:

git clone [email protected]:joeyespo/gitpress-blog.git
cd gitpress
git push git://localhost/

Pull-based

Note: this feature is still being developed, planned for next release.

Pull-based is similar to push-based, only you'll provide the repository to pull from, guaranteeing it comes from the right place. You'll be able to trigger a pull manually from the Admin interface or by setting up post-receive hooks.

import gitpress

if __name__ == '__main__':
    gitpress.run('http://github.com/joeyespo/gitpress-blog.git')

Save the above to a file called pull_server.py and run it:

$ python pull_server.py
 * Running on http://localhost:5000/

External servers

To use with external powerhouse servers, you'll need to expose the WSGI application object. Do this by instantiating the Server object directly:

import gitpress

app = gitpress.Server('http://github.com/joeyespo/gitpress-blog.git')

if __name__ == '__main__':
    app.run(port=8080)

Configuration

Like the preview, you can further configure Gitpress by visiting the Admin page of your blog with the browser. You can also configure Gitpress directly using the API, or design it to consume its own command-line arguments. The next section goes into more detail and demonstrates the flexibility of the API.

The Python API

TODO