Nesta CMS

A Ruby CMS. Built with Sinatra.

Metadata reference

As you've probably noticed, Nesta doesn't use a database. As a result
there's no obvious place to store information about a web page, such
as the date that it was published.

Nesta solves this problem by allowing you to specify metadata at the top
of your Markdown file. You just write the name of the metadata field, a
colon, a space, and then the value of the metadata.

Here's a contrived example:

Summary: This is a blog post about carrots. Juicy orange carrots!
Read more: Find out about this superb vegetable
Date: 6 Oct 2009

There's not much to go wrong here, but bear in mind that:

Each piece of metadata should be entered on a single line, and

there can be no blank lines between metadata fields.

The first blank line is assumed to separate the metadata from the
content. You'll typically follow your metadata with the page's main
heading:

Date: 6 Oct 2009
# Carrots
...

Note: Plenty of file-based blogging platforms use a similar approach, but they
don't all use the same format. If you're switching to Nesta from a
system that stores its metadata in Yaml, there's a plugin for
that!

Without further ado, here's a full list of the Nesta metadata.

Articles heading

When articles are listed on a category page, Nesta adds a heading above
the articles based on the category's title (e.g. "Articles on Thing" if
the category page's main heading is "Thing"). Sometimes prefixing the
name of a page with "Articles on" just doesn't make sense. If you set
the 'Articles heading' metadata on the category page, Nesta will allow
you to override the heading.

Example:

Articles heading: The blog posts

Atom ID

An alternative to RSS, Atom feeds can alert your readers to new
articles that you publish on your site. Each item in an Atom feed must
be assigned a globally unique identifier, which allows feed reader
software to determine whether or not an article has already been read by
the user.

Nesta determines Atom IDs for new articles automatically (using these
guidelines),
so you don't normally need to choose the Atom ID yourself.

It is useful to set the Atom ID if you are:

Moving an article (i.e. any page with a date) to a new URL. You
should set it to the article's Atom ID at the previous location.

Importing content from another CMS or blogging system to the IDs
that were generated by your previous software, which ensures that
feed readers do not redisplay any old content to your users.

Example:

Atom ID: tag:localhost,2009-03-08:/articles/my-article

Description meta tag

If you define Description your HTML page will have a description meta
tag. The contents of this tag are often displayed by search engines to
give a potential visitor a good feel for the contents of the page, and
help to indicate the relevancy of your web page to a search engine. Try
to set your description text to one or two short, relevant sentences.

Example:

Description: A short summary of the British breakfast.
# British breakfasts
...

Categories

Pages can be listed on relevant category pages. Assuming you want your
page or article to appear on your Git, Ruby and Rails category pages
(whose filenames are git.mdown and ruby.mdown), you could do this:

Categories: git, ruby, ruby/rails

When multiple pages are listed in the same category they will be sorted
by their headings, unless you also specify a priority. You set the
priority of a page within each of its categories separately:

Categories: git:5, ruby, ruby/rails:-1

When a category page is rendered the pages with the highest priority are
listed first. The default priority is 0.

Note that priorities don't have any effect when used on an article (i.e.
a page with a date -- see below). Articles are always sorted
chronologically, with the most recent one at the top of the page.

Date

Sets the date on which an article was published. You can use any form
that is understood by Ruby's DateTime.parse method. It's pretty
liberable in what it accepts -- all of these examples work:

You must set the date on an article if you want it to appear in the Atom
feed (the most recent 10 articles are included, in reverse chronological
order). Note that Nesta only displays the date on which an article was
published, not the time. You can still use the time to control the sort
order of multiple articles that are published on the same day, however.

If you set the date to some time in the future your article won't be
published until that time is reached (thanks to Glenn Gillen
for the patch).

Time zones

All times are considered to be in the server's local time zone (for well
configured servers, this will be UTC) unless you specify the timezone
yourself. If you want to specify the time zone, be sure to include the
time. If you omit the time, but include the time zone, Ruby will ignore
the time zone.

To put that another way, this will publish the article at midnight in
New York:

Date: 23 July 2008 00:00 EST

This will publish the article at midnight in London, which probably
isn't what you wanted.

Date: 23 July 2008 EST

Flags

The 'Flags' metadata allows you to mark some pages as special, in some way. For example:

Flags: draft, awesome

You can use any text you like to flag a page. Multiple flags are separated by
commas. Only the "draft" flag currently has any special meaning in Nesta -- any
page marked as draft will show up on a development site (e.g. on your own
computer) but will be hidden on your live web site.

If you add your own flags to a page you can check whether a page has a flag set
(e.g. in your view) by calling the flagged_as? method. Here's an example:

- if @page.flagged_as?('awesome')
%p This page is awesome!

You get the idea...

Keywords meta tag

The Keywords metadata sets the HTML keywords meta tag for your page.
Keywords were historically used to indicate to search engines which
topics a page is about. Google doesn't pay much attention to the
keywords meta tag these days, but some other search engines still do.

Layout

Each page in a Nesta web site is rendered using two files that describe
the HTML markup; the layout template and the page template. The layout
usually contains HTML that is common to every page on your site (e.g.
header, side bar), while the page template will contain HTML that is
common to a certain group of pages on the site. Nesta places no
restrictions on you here though; you can create as many separate layouts
or page templates as you wish.

You can control which layout is used to render a page by specifying the
Layout metadata (also see the docs for the Template metadata below).

Example:

Layout: signup
# Sign-up now before it's too late!
...

You'll need to create a layout template in your views directory, and
call yield somewhere within it to render the page specific template
inside the layout. See the default layout for an example.

Link text

Nesta will generate links to your pages (e.g. in menus and breadcrumbs),
using page headings in the text of the links. If you'd rather link to
a page with different text, you can define it like this:

Link text: Short and snappy
# Long and wordy title that you don't want in your menu
...

Read more

When the summary of an article (see below) is displayed on the home
page, or on a category page, there is a link underneath the summary that
points to the rest of the post. By default this link contains the text
"Continue reading", but you can override it if you prefer.

Example:

Read more: Read more about this stunning topic

Summary

The summary text allows you to include a brief precis of your article on
your home page or category page. If you don't define a summary the
entire article will be displayed instead, which for short articles may
be just what you want.

As blank lines are not allowed within (or between) metadata fields you
cannot insert multiple paragraphs into your summary by inserting blank
lines. You can however insert the "new line" character (\n) which will
insert paragraph breaks into your summary field.

Example:

Summary: First paragraph.\nSecond paragraph.
# Main heading
First paragraph.
Second paragraph, which is different to the summary's version.

Summaries aren't automatically prepended to the body copy, so can be
quite independent from the opening paragraphs of your article.

The summary is not used in the site's Atom feed; the complete article is
included in the feed instead.

Template

Each page in a Nesta web site can be rendered with a different HTML
template. By default the page template is used, which is defined in
the page.haml file in your views directory.

If your site has several different types of page, each of which occurs
multiple times, it can be useful to create separate templates with which
to render them. Create more templates in your views directory and then
use them on a page by setting the Template metadata.

Example:

Layout: shop
Template: product
# Our flugelbinders
...

As you can see, it's also possible to control which layout is used with
the Layout metadata (which is described in its own section above).

Defining your own metadata

Nesta's metadata is extensible; you can add your own fields and then
access them from your templates. For example:

My own metadata: A value of your choosing
# Carrots
...

In your page template (or your app.rb file) you could then write this
to access the value that was set on the page: