/release/README.html
HTML | 314 lines | 285 code | 29 blank | 0 comment | 0 complexity | 243f125ad8ee5fdd74a81951356e78b9 MD5 | raw file
1<?xml version="1.0" encoding="utf-8" ?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 4<head> 5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 6<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> 7<title>Blogmaker™ blog application for Django</title> 8<style type="text/css"> 9 10/* 11:Authors: Ian Bicking, Michael Foord, Kent Johnson 12:Contact: fuzzyman@voidspace.org.uk 13:Date: 2005/08/26 14:Version: 0.1.0 15:Copyright: This stylesheet has been placed in the public domain. 16 17Stylesheet for Docutils. 18Based on ``voidspace.css`` by Ian Bicking and Michael Foord 19``blue_box.css`` by Ian Bicking 20and ``html4css1.css`` revision 1.46. 21*/ 22 23@import url(http://rst2a.com/static/styles/html/default.css); 24 25body { 26 font-family: Verdana,"Lucida Grande",Lucida,sans-serif;; 27 font-size: 13px; 28} 29 30em, i { 31 /* Typically serif fonts have much nicer italics */ 32 font-family: Times New Roman, Times, serif; 33} 34 35a.target { 36 color: blue; 37} 38 39a.target { 40 color: blue; 41} 42 43a.toc-backref { 44 text-decoration: none; 45 color: black; 46} 47 48a.toc-backref:hover { 49 background-color: inherit; 50} 51 52a:hover { 53 background-color: #cccccc; 54} 55 56div.attention, div.caution, div.danger, div.error, div.hint, 57div.important, div.note, div.tip, div.warning { 58 background-color: #cccccc; 59 padding: 3px; 60 width: 80%; 61} 62 63div.admonition p.admonition-title, div.hint p.admonition-title, 64div.important p.admonition-title, div.note p.admonition-title, 65div.tip p.admonition-title { 66 text-align: center; 67 background-color: #999999; 68 display: block; 69 margin: 0; 70} 71 72div.attention p.admonition-title, div.caution p.admonition-title, 73div.danger p.admonition-title, div.error p.admonition-title, 74div.warning p.admonition-title { 75 color: #cc0000; 76 font-family: sans-serif; 77 text-align: center; 78 background-color: #999999; 79 display: block; 80 margin: 0; 81} 82 83h1, h2, h3, h4, h5, h6 { 84 font-family: Helvetica, Arial, sans-serif; 85 border: thin solid black; 86 padding: 4px 4px 1px; 87} 88 89h1 { 90 background-color: #137DBF; 91 color: #ffffff; 92 font-size:20px; 93} 94 95h1 a.toc-backref, h2 a.toc-backref { 96 color: #ffffff; 97} 98 99h2 { 100 background-color: #666666; 101 color: #ffffff; 102 border: medium solid black; 103} 104 105h3, h4, h5, h6 { 106 background-color: #cccccc; 107 color: #000000; 108} 109 110h3 a.toc-backref, h4 a.toc-backref, h5 a.toc-backref, 111h6 a.toc-backref { 112 color: #000000; 113} 114 115h1.title { 116 text-align: center; 117} 118 119table.footnote { 120 padding-left: 0.5ex; 121} 122 123table.citation { 124 padding-left: 0.5ex 125} 126 127pre.literal-block, pre.doctest-block { 128 border: thin black solid; 129 padding: 5px; 130} 131 132.image img { border-style : solid; 133 border-width : 2px; 134} 135 136h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { 137 font-size: 100%; 138} 139 140code, tt { 141 color: #000066; 142} 143 144tt.docutils { 145 background-color:#FFFFFF; 146} 147</style> 148</head> 149<body> 150<div class="document" id="blogmaker-tm-blog-application-for-django"> 151<h1 class="title">Blogmaker™ blog application for Django</h1> 152<p>Blogmaker 0.6, January 2008</p> 153<p>Blogmaker™ is a full-featured, production-quality blogging application for Django. 154It supports trackbacks, ping and comments with moderation and honeypot spam prevention.</p> 155<p>Blogmaker is released under a BSD license. You may "copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software" (to borrow a phrase from the more-or-less equivalent "MIT License").</p> 156<p>Caveat: the current release (including these docs) is for people who are already familiar with Django or willing to poke around a bit. We developed Blogmaker for our own projects, though we hope it will help others leverage the awesome Django framework to create feature-rich blogs. We have additional features planned, and welcome contributions from others.</p> 157<div class="contents topic"> 158<p class="topic-title first"><a id="contents" name="contents">Contents</a></p> 159<ul class="simple"> 160<li><a class="reference" href="#features" id="id1" name="id1">Features</a></li> 161<li><a class="reference" href="#download-and-support" id="id2" name="id2">Download and support</a></li> 162<li><a class="reference" href="#credits" id="id3" name="id3">Credits</a></li> 163<li><a class="reference" href="#requirements" id="id4" name="id4">Requirements</a></li> 164<li><a class="reference" href="#settings" id="id5" name="id5">Settings</a></li> 165<li><a class="reference" href="#other-setup-and-tips" id="id6" name="id6">Other setup and tips</a></li> 166<li><a class="reference" href="#blogmaker-tools" id="id7" name="id7">Blogmaker Tools</a></li> 167<li><a class="reference" href="#other-blog-applications" id="id8" name="id8">Other blog applications</a></li> 168</ul> 169</div> 170<div class="section"> 171<h1><a class="toc-backref" href="#id1" id="features" name="features">Features</a></h1> 172<ul class="simple"> 173<li>Create and edit blog entries with the Django admin interface or a custom interface with preview</li> 174<li>Blog entries may be marked up as HTML or <a class="reference" href="http://daringfireball.net/projects/markdown/">Markdown</a> text (using <a class="reference" href="http://www.freewisdom.org/projects/python-markdown/">python-markdown</a>)</li> 175<li>Comment on blog entries (based on django.contrib.comments)</li> 176<li>Comment honeypot for transparent spam protection, based on ideas from <a class="reference" href="http://www.nedbatchelder.com/text/stopbots.html">http://www.nedbatchelder.com/text/stopbots.html</a></li> 177<li>Comment moderation, based on James Bennett's <a class="reference" href="http://code.google.com/p/django-comment-utils/">comment_utils</a></li> 178<li>Profanity and safe HTML filters for comments</li> 179<li>Ping other sites when blog entries are added (thanks to <a class="reference" href="http://www.imalm.com/blog/2007/feb/10/using-django-signals-ping-sites-update/">iMalm.com</a>)</li> 180<li>Post trackbacks to other blogs</li> 181<li>Receive trackbacks from other blogs, checking that the referring page does link to the referenced entry to reduce trackback spam</li> 182<li>Independent RSS feeds for posts and comments</li> 183<li>Archives by year, month and day; the day archive includes navigation links to every other day in the month which contains a post</li> 184<li>Tags, including a tag index page</li> 185<li>Sidebars for tags and recent posts</li> 186<li>Previous and next links include post titles</li> 187<li>Search blog entries</li> 188<li>Multiple authors and archive by author</li> 189<li>Scheduled posts</li> 190<li>Optionally host the blog from its own domain or subdomain</li> 191</ul> 192<p>Blogmaker is production-ready; it powers our two blogs at <a class="reference" href="http://blog.blogcosm.com/">http://blog.blogcosm.com/</a> and <a class="reference" href="http://prefabcosm.com/blog/">http://prefabcosm.com/blog/</a>.</p> 193</div> 194<div class="section"> 195<h1><a class="toc-backref" href="#id2" id="download-and-support" name="download-and-support">Download and support</a></h1> 196<p>The latest release of this document is available at <a class="reference" href="http://blogmaker.googlecode.com/svn/trunk/release/README.html">http://blogmaker.googlecode.com/svn/trunk/release/README.html</a>. 197Blogmaker can be downloaded from the Google Code project at <a class="reference" href="http://code.google.com/p/blogmaker/">http://code.google.com/p/blogmaker/</a> or the Python Package Index at <a class="reference" href="http://pypi.python.org/pypi/Blogmaker/">http://pypi.python.org/pypi/Blogmaker/</a>. If you have any questions, comments or patches, please send email to the <a class="reference" href="http://groups.google.com/group/blogmaker-users">blogmaker-users</a> group.</p> 198</div> 199<div class="section"> 200<h1><a class="toc-backref" href="#id3" id="credits" name="credits">Credits</a></h1> 201<div class="line-block"> 202<div class="line">Scott S. Lawton: product manager</div> 203<div class="line">Peter Bernheim: primary developer</div> 204<div class="line">Kent S Johnson: developer and in-house Python expert</div> 205</div> 206<p>Blogmaker is a trademark of PreFab Software, Inc.</p> 207<p>Portions of Blogmaker are based on the blog application example at <a class="reference" href="http://www.23excuses.com/2006/Jul/07/23-excuses-release-and-introduction/">23 excuses</a> and Copyright © 2006, Andrew Gwozdziewycz.</p> 208<p>Portions of blogmaker.comments are based on James Bennett's <a class="reference" href="http://code.google.com/p/django-comment-utils/">comment_utils</a> and Copyright © 2007, James Bennett.</p> 209<p>Portions of blogmaker.comments are based on django.contrib.comments and are Copyright © 2005, the Lawrence Journal-World.</p> 210<p>See the file LICENSE.txt for details.</p> 211<p>jQuery 1.2.1 is Copyright © 2007 John Resig (jquery.com) and Dual licensed under the MIT (MIT-LICENSE.txt) and GPL (GPL-LICENSE.txt) licenses. Blogmaker includes it under the provisions of the MIT license.</p> 212<p>feedparser is Copyright © 2002-2006, Mark Pilgrim, All rights reserved.</p> 213</div> 214<div class="section"> 215<h1><a class="toc-backref" href="#id4" id="requirements" name="requirements">Requirements</a></h1> 216<p>Blogmaker requires Python 2.5; earlier versions will not work. Blogmaker works with Django 0.96; it has not been tested with later releases.</p> 217<p>Blogmaker processes blog entries with <a class="reference" href="http://www.freewisdom.org/projects/python-markdown/">python-markdown</a>. It requires <a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=153041&package_id=183331&release_id=533142">python-markdown 1.6b</a> specifically; earlier versions are buggy and later versions are not backwards-compatible.</p> 218<p>To include images in blog entries, you must have <a class="reference" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> installed. This is a requirement of Django's <a class="reference" href="http://www.djangoproject.com/documentation/0.96/model-api/#imagefield">ImageField</a>.</p> 219<p>In order to install Blogmaker, you must first set up a basic Django site with the usual settings file, base template, and primary urls.py. More information can be found at <a class="reference" href="http://www.djangoproject.com/">http://www.djangoproject.com/</a></p> 220<p>Blogmaker requires the installation of two (included) Django applications:</p> 221<ol class="arabic simple"> 222<li>blogmaker.comments (which can be used on the non-blog portions of a site)</li> 223<li>blogmaker.util (a set of utilities shared internally with our unreleased non-blog code)</li> 224</ol> 225<p>Blogmaker uses <a class="reference" href="http://www.aswmc.com/dbmigration/">DbMigration</a> to update the database. DbMigration is required only for future schema evolution; if there are future schema changes, we plan to include migrations to update the database as required. Although DbMigration works with any database, our usage is specific to PostgreSQL; using our migrations with other databases will require some changes.</p> 226<p>Other features of Blogmaker will work with any Django-compatible database engine.</p> 227</div> 228<div class="section"> 229<h1><a class="toc-backref" href="#id5" id="settings" name="settings">Settings</a></h1> 230<p>Blogmaker requires a number of settings to be defined in your settings file:</p> 231<dl class="docutils"> 232<dt><tt class="docutils literal"><span class="pre">INSTALLED_APPS</span></tt></dt> 233<dd>Add <tt class="docutils literal"><span class="pre">'blogmaker.blog'</span></tt>, <tt class="docutils literal"><span class="pre">'blogmaker.comments'</span></tt> and <tt class="docutils literal"><span class="pre">'blogmaker.util'</span></tt> to the list of installed applications. We also require some or all of these standard applications:</dd> 234</dl> 235<div class="line-block"> 236<div class="line">django.contrib.auth</div> 237<div class="line">django.contrib.contenttypes</div> 238<div class="line">django.contrib.sessions</div> 239<div class="line">django.contrib.humanize</div> 240<div class="line">django.contrib.sites</div> 241<div class="line">django.contrib.markup</div> 242<div class="line">django.contrib.admin</div> 243</div> 244<dl class="docutils"> 245<dt><tt class="docutils literal"><span class="pre">TEMPLATE_CONTEXT_PROCESSORS</span></tt></dt> 246<dd>Blogmaker's comment application requires that <tt class="docutils literal"><span class="pre">django.core.context_processors.request</span></tt> be one of your installed context processors. This puts a <tt class="docutils literal"><span class="pre">request</span></tt> object in the context. The comment honeypot uses this to access the IP address of a request.</dd> 247<dt><tt class="docutils literal"><span class="pre">DEFAULT_BLOG_USER</span></tt></dt> 248<dd>The id of the primary blog user, as defined by the Django Auth/User model.</dd> 249<dt><tt class="docutils literal"><span class="pre">LOG_DIRECTORY</span></tt></dt> 250<dd>The directory where log files will be written.</dd> 251<dt><tt class="docutils literal"><span class="pre">COPYRIGHT</span></tt></dt> 252<dd>Your copyright text, e.g. "All contents Copyright 2007, Acme Inc."</dd> 253<dt><tt class="docutils literal"><span class="pre">SITE_ROOT</span></tt></dt> 254<dd>Defines the root URL of your site, e.g. <a class="reference" href="http://domain.com/">http://domain.com/</a></dd> 255<dt><tt class="docutils literal"><span class="pre">BLOG_MEDIA_PREFIX</span></tt></dt> 256<dd>URL prefix for where you will serve the media directory contained at blogmaker.blog.media. Make sure to use a trailing slash. 257Examples: "/media/blog/", "<a class="reference" href="http://foo.com/media/blog/">http://foo.com/media/blog/</a>"</dd> 258<dt><tt class="docutils literal"><span class="pre">ADMIN_MEDIA_PREFIX</span></tt></dt> 259<dd>URL prefix for admin media -- CSS, JavaScript and images. Make sure to use a trailing slash. 260Examples: "/media/admin/", "<a class="reference" href="http://foo.com/media/admin/">http://foo.com/media/admin/</a>"</dd> 261<dt><tt class="docutils literal"><span class="pre">BLOG_ROOT</span></tt></dt> 262<dd>Defines the root URL for the blog path, e.g. if you want the blog to live at <a class="reference" href="http://domain.com/blog/">http://domain.com/blog/</a>, this variable would be set to '/blog/'. If you want the blog to live at a different subdomain than the rest of the site, you will need to set an absolute URL: '<a class="reference" href="http://blog.domain.com/">http://blog.domain.com/</a>'</dd> 263</dl> 264<p>If you include images in your blog entries, you should set <tt class="docutils literal"><span class="pre">MEDIA_ROOT</span></tt> and <tt class="docutils literal"><span class="pre">MEDIA_URL</span></tt> as described in the <a class="reference" href="http://www.djangoproject.com/documentation/0.96/settings/#media-root">Django documentation</a>. You must also configure your server to serve files from <tt class="docutils literal"><span class="pre">MEDIA_ROOT</span></tt> at <tt class="docutils literal"><span class="pre">MEDIA_URL</span></tt>.</p> 265<p>The following should be set if you enable email notification for comment/trackback features:</p> 266<dl class="docutils"> 267<dt><tt class="docutils literal"><span class="pre">MANAGERS</span></tt></dt> 268<dd>A list of <tt class="docutils literal"><span class="pre">('Name',</span> <span class="pre">'email</span> <span class="pre">address')</span></tt> tuples defining the people to whom notification emails will be sent.</dd> 269<dt><tt class="docutils literal"><span class="pre">DEFAULT_FROM_EMAIL</span></tt></dt> 270<dd>The default e-mail you would like e-mails to be sent from.</dd> 271</dl> 272<p>Blogmaker uses Django's profanity filter. You can specify a list words to reject by setting <tt class="docutils literal"><span class="pre">PROFANITIES_LIST</span></tt>.</p> 273</div> 274<div class="section"> 275<h1><a class="toc-backref" href="#id6" id="other-setup-and-tips" name="other-setup-and-tips">Other setup and tips</a></h1> 276<p>Add a reference to <tt class="docutils literal"><span class="pre">blogmaker.blog.urls</span></tt> and <tt class="docutils literal"><span class="pre">blogmaker.blog.admin_urls</span></tt> to your <tt class="docutils literal"><span class="pre">urls.py</span></tt> with any desired prefix, for example:</p> 277<pre class="literal-block"> 278(r'^blog/', include('blogmaker.blog.urls')), 279(r'^blogmaker/', include('blogmaker.blog.admin_urls')), 280</pre> 281<p>Comments are moderated using a version of <a class="reference" href="http://code.google.com/p/django-comment-utils/">comment_utils</a>. The setup is the same as for comment_utils. For example, to moderate first-time comments with email notification, include this code in your project:</p> 282<pre class="literal-block"> 283from blogmaker.comments.moderation import ModerateFirstTimers, moderator 284from blogmaker.blog.models import Entry 285 286class Moderator(ModerateFirstTimers): 287 email_notification = True 288 289moderator.register(Entry, Moderator) 290</pre> 291<p>See the <a class="reference" href="http://django-comment-utils.googlecode.com/svn/trunk/docs/">comment_utils docs</a> for more options. This code must run once when your server starts up. <a class="reference" href="http://www.b-list.org/weblog/2007/nov/05/server-startup/">This blog post</a> has some suggestions of where to put startup code.</p> 292<p>Note: Blogmaker contains forked copies of both django.contrib.comments and comment_utils. You do not need to install the standard comments and comment_utils applications to use Blogmaker.</p> 293<p>Blog entries may be written in straight HTML or using <a class="reference" href="http://daringfireball.net/projects/markdown/">Markdown</a> markup. Blogmaker also defines a few shortcuts in the form <tt class="docutils literal"><span class="pre">%portal%</span></tt>. See <tt class="docutils literal"><span class="pre">expand_shortcuts()</span></tt> in <tt class="docutils literal"><span class="pre">util/__init__.py</span></tt> for the full list.</p> 294<p>Trackbacks to other blogs are not posted automatically. To post trackbacks, run <tt class="docutils literal"><span class="pre">blogmaker.blog.trackback_update.py</span></tt>. You may want to run this from a cron job.</p> 295<p>View, modify and post trackbacks for an individual blog entry by adding <tt class="docutils literal"><span class="pre">/postTrackbacks/</span></tt> to the public URL for the entry.</p> 296<p>Trackbacks may be posted to a Blogmaker entry using the public URL for the entry with the suffix <tt class="docutils literal"><span class="pre">/trackback/</span></tt>. To reduce trackback spam, any posted trackbacks are validated by fetching the contents of the referring page and verifying that the entry URL appears on the referring page. In addition, trackbacks are comments and may be moderated like any other comment.</p> 297</div> 298<div class="section"> 299<h1><a class="toc-backref" href="#id7" id="blogmaker-tools" name="blogmaker-tools">Blogmaker Tools</a></h1> 300<p>Blogmaker Tools adds a preview option and an improved list view as an alternative to Django's built-in admin site. The tools are accessed from the <tt class="docutils literal"><span class="pre">/tools/</span></tt> URL.</p> 301</div> 302<div class="section"> 303<h1><a class="toc-backref" href="#id8" id="other-blog-applications" name="other-blog-applications">Other blog applications</a></h1> 304<p>There are several other blogging applications for Django:</p> 305<ul class="simple"> 306<li>The <a class="reference" href="http://www.23excuses.com/2006/Jul/07/23-excuses-release-and-introduction/">23 excuses</a> application that was the start of Blogmaker (version 1.0, 2006-07-07) (download link broken at the moment)</li> 307<li><a class="reference" href="https://launchpad.net/banjo">Banjo</a> - "A Django blog with bells and whistles" from Bruce Kroeze, <a class="reference" href="http://coderseye.com/">http://coderseye.com/</a>. Not yet available - "nearing 0.1 release" as of 2007-11-25.</li> 308<li><a class="reference" href="http://code.google.com/p/coltrane-blog/">Coltrane</a> by James Bennett, <a class="reference" href="http://www.b-list.org/">http://www.b-list.org/</a>. A bit empty as of 2007-12-05 but there is code if you look at svn.</li> 309<li><a class="reference" href="http://code.ibofobi.dk/public/wiki/ProjectIbofobiBlog">ibofobi</a> version 0.1, 2005-12-09</li> 310</ul> 311</div> 312</div> 313</body> 314</html>