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:
Date: 23 July 2008
Date: July 23 2008
Date: 14:13, 23 July 2008
Date: 23 July 2008 2:13pm
Date: 23 July 2008 14:13
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.
Example:
Keywords: breakfast, cholesterol, heart bypass
# British breakfasts
...
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:
@page.metadata('my own metadata')
Note that the text passed to the metadata method is in lower case.