Settings

Mango provides a range of configurable options — settings — which allow its functionality to be extended and its behaviour tweaked. For example, commenting is not enabled by default, but can be switched on by configuring a setting.

Mango ships with a default settings file, defaults.py, which is required and should not be edited. This file contains all the settings necessary to get an installation up and running.

Mango allows settings to be configured via a custom settings file, custom.py, which needs to be created (and saved in the settings directory). This ensures that customizations are not overwritten by Mango updates.

Below is an alphabetical list of Mango's configurable settings.

`AKISMET_API_KEY`

Optional.

This setting enables Mango to filter comments through Akismet, dramatically reducing the number of comments requiring manual moderation.

Akismet API keys are free for personal use.

`AUTHORS`

Optional.

This setting associates URLs with a site's authors, allowing templates to display an author's name as a link to his or her home on the Web.

AUTHORS = {
    'Chris Chambers': 'http://chrischambers.name/',
    'David Chambers': 'http://davidchambersdesign.com/',
    '_why': None,
}

There's no need to include authors who don't wish to have their name link anywhere, but there's no harm in doing so.

Templates can access this information via document.author.name and document.author.url.

`BASE_URL`

Default: None

The URL at which the Mango site is mounted.

`COMMENTS_REQUIRE_APPROVAL`

Default: True

Determines whether unmoderated comments are displayed. When True, only approved comments are displayed.

If False, it's a good idea to include AKISMET_API_KEY to prevent spam comments from being displayed.

`CONTACT_FORM`

Default: True

When True, a contact form is accessible at /contact/. Messages submitted via this form are e-mailed to the address specified by PRIMARY_AUTHOR_EMAIL.

`CSS`

Default: ('/static/', ('screen', 'default.css'))

This setting provides an alternative to hard-coding style sheet references in the base template, making it possible to skin existing templates — such as Mango's defaults — without modifying them.

Since the ordering of style sheets is relevant, a tuple of tuples is used rather than a dictionary.

CSS = ('/static/styles/',
    ('all', 'reset.css'),
    ('print', 'print.css'),
    ('screen', ('screen.css', 'pictos.css')),
)

Much like Django's patterns function, the first item is a prefix. The above would result in the following markup appearing in each page head.

<link rel="stylesheet" href="/static/styles/reset.css" media="all" />
<link rel="stylesheet" href="/static/styles/print.css" media="print" />
<link rel="stylesheet" href="/static/styles/screen.css" media="screen" />
<link rel="stylesheet" href="/static/styles/pictos.css" media="screen" />

Note that for media types with only one style sheet, a string may be used in favour of a tuple or list with just one item – i.e. ('all', 'reset.css') is equivalent to ('all', ('reset.css',)).

`DISPLAY_DATE_FORMAT`

Default: '%d %B %Y'

The Python date format used by the display_date template tag.

`DISPLAY_TIME_FORMAT`

Default: u'%i:%M\u2009%p'.encode('utf-8')

The Python time format used by the display_time template tag.

`DISQUS_API_KEY`

Optional.

Disqus user key. Must be set correctly to enable commenting.

`DISQUS_SHORTNAME`

Optional.

Disqus site shortname. Must be set correctly to enable commenting.

`DOCUMENTS_PATH`

Default: 'mango/examples'

The path to the documents directory, either as an absolute path or relative to the Django project in which the Mango application resides.

`FEED_MAX_POSTS`

Default: 20

The maximum number of posts to include in the Atom feed.

Set to 0 to have all posts appear in the feed.

`GOOGLE_ANALYTICS_ID`

Optional.

The default base template inserts asynchronous Google Analytics tracking code if this setting is specified.

`GRAVATAR_DEFAULT`

Optional.

Default image URL. If omitted, Gravatar's default image is used when needed.

Note that Gravatar also accepts special values in the place of an image URL: "404", "identicon", "mm", "monsterid", "retro", and "wavatar".

`GRAVATAR_SIZE`

Default: 32

Gravatar image size in pixels, in the range 1 to 512.

`INDEX_CACHE_SECONDS`

Default: 5 * 60 (5 minutes)

The length of time for which Mango's cache of all a site's documents should remain valid. Mango does not consult the file system each time a page is requested, so there is a trade-off between "freshness" and performance.

Set to 0 to disable index caching.

`JS`

Default: ('/static/',)

Tuple containing a prefix followed by zero or more paths to scripts.

JS = ('/static/scripts/',
    'jquery.js',
    'jquery.localize.js',
    'global.js',
)

The above would result in the following markup appearing near the bottom of each page body.

<script src="/static/scripts/jquery.js"></script>
<script src="/static/scripts/jquery.localize.js"></script>
<script src="/static/scripts/global.js"></script>

`MARKDOWN_EXTENSIONS`

Default: ('def_list', 'fenced_code')

Lists the Python-Markdown extensions that are to be used.

`META_LISTS`

Default: ('tags',)

Specifies the metadata attributes whose values should be split into lists. For example, tags: accessibility, CSS, UX becomes ['accessibility', 'CSS', 'UX'] and tags: iPhone becomes ['iPhone'].

If META_LISTS contains 'tags', a tags page is accessible at /tags/. If you're not tagging your documents, set META_LISTS to a tuple that does not contain 'tags'.

`PATH_TO_STATIC`

Default: 'mango/static'

The path to the static media directory, either as an absolute path or relative to the Django project in which the Mango application resides.

`POST_CACHE_SECONDS`

Default: 24 * 60 * 60 (24 hours)

When Mango encounters a document which has been modified since it was last cached, Mango will always open the document and parse it. In theory, therefore, documents could be cached with no expiry time.

As a safety measure, Mango provides this setting which dictates the maximum number of seconds for which a cached document remains valid.

Set to 0 to disable document caching.

`PRIMARY_AUTHOR_EMAIL`

Default: None

Used as the author email in Atom feeds. Also used — in conjunction with AUTHORS — to determine which comments are author comments.

`PRIMARY_AUTHOR_NAME`

Default: 'Admin'

Templates can apply this value to posts that do not explicitly declare an author. Also used as the author name in Atom feeds unless empty.

`PRIMARY_AUTHOR_URL`

Default: None

Used as the author uri in Atom feeds.

`REPLACEMENTS`

Default: True

When True, the following replacements are made in the title and body of each post:

[full stop][full stop][full stop] → [ellipsis]
[space][hyphen][hyphen][space] → [thin space][em dash][thin space]

In the future this may be replaced by a tuple containing the replacement pairs.

`SHORT_URL_BASE`

Optional.

Since John Gruber registered ✪df.ws and started to roll his own short URLs, some of the hip young kids have started to do the same.

Mango supports this approach very nicely. If John were to publish a document named 1=my-first-post.text, its short URL would be http://✪df.ws/1/.

`SITE_TITLE`

Default: 'I ♥ Mangoes'

Makes the site's title accessible to templates to avoid hard-coding.

`SUBSCRIPTIONS`

Default: False

When True, commenters have the option of subscribing to future comments on a thread. Note that a database is required to store these subscription lists.