Nesta CMS

Refresh the browser when you save a file

2013-02-15T00:00:00+00:00

Most of the pages on a Nesta site are written in a text editor, using Markdown or Textile. You don’t get to see what your words look like on a web page until you save the file to disk and reload your browser. Wouldn’t it be nice if your browser automatically reloaded pages as you saved them? When designing a theme, what if changes to HTML and CSS were reloaded immediately?

With the livereload and Guard projects, it’s fairly easy to setup.

Note: Since I wrote this article, Livereload 2 has been released. It looks as though that’s an even easier way to reload your pages, but I haven’t had a chance to try it with Nesta yet. These instructions are for Livereload 1.

Installing guard

Guard is distributed as a Ruby gem. We actually want the guard-livereload gem (which will pull in guard itself) so we’ll add that to our Gemfile. We’re going to add the rb-readline gem too, as it gives Guard a nice interactive prompt:

$ cat >> Gemfile
group :development do
  gem 'guard-livereload'
  gem 'rb-readline'
end

Now re-build your bundle to install the extra gems…

$ bundle

That’s Guard installed.

Installing the browser plugin

Head over to the plugin instructions and download and install the browser plugin.

Setting up your Guardfile

Now we just need to create a Guardfile that will tell Guard what we want it to do. You can create the default config file like this:

$ guard init livereload

If you have a look at the Guardfile you’ll see a few watch commands that specify paths to files that you’d find in a Rails app. Nesta keeps things in different places to Rails, so we’ll be changing the contents of that file.

Mine looks like this:

$ cat > Guardfile
guard 'livereload' do
  watch(%r{content/pages(/.+)\.(mdown|textile|haml)}) { |match| match[1] }
  watch(%r{public(/.+\.(jpe?g|js|png))}) { |match| match[1] }
  watch(%r{views/.+\.haml})
  watch(%r{views/(.+)\.s[ac]ss}) do |match|
    if match[1] =~ /(mixins|variables)/
      ["/css/master.css", "/css/layout.css"]
    else
      "/css/#{match[1]}.css"
    end
  end
end

I won’t go into too much detail about what’s going on there; I think you’ll do better by studying the code than you would at reading my attempt to explain it. The only thing I want to point out is that I usually have Sass files called views/mixins.sass and views/variables.sass. Those two files are never served to the browser; they’re just included into master.sass and layout.sass. That’s why when they change, Guard tells the browser to reload master.css and layout.css.

When you’re happy with your config, run Guard like this:

$ guard

If you make some changes to Guardfile while guard is running you can prompt Guard to reload its config by typing “reload” at Guard’s prompt.

Try it out

Run guard in one terminal window, and your local web server in another. Visit a web page, then right click in the browser window and select “Enable Livereload”.

Any changes that you make to your content, HTML or CSS should now cause your browser to automatically reload.

If you want to see what else Guard can do, Ryan Bates has recorded a Railscast on Guard (livereload is introduced after 6 minutes and 20 seconds).

Make a page that lists old articles

2013-02-15T00:00:00+00:00

Out of the box, Nesta doesn’t provide a page that lists all your old blog posts. It is however, easy to add one.

This recipe will walk you through how to add a page to your site at /archives that lists all your blog posts, organised by the year in which they were written.

A dash of Ruby

If you don’t already have one, create a file called app.rb in your project’s directory, and paste the following code into it (if you do have one, just add the code that follows to your app.rb file).

module Nesta
  class App
    helpers do
      def list_articles(articles)
        haml_tag :ol do
          articles.each do |article|
            haml_tag :li do
              haml_tag :a, article.heading, :href => url(article.abspath)
            end
          end
        end
      end

      def article_years
        articles = Page.find_articles
        last, first = articles[0].date.year, articles[-1].date.year
        (first..last).to_a.reverse
      end

      def archive_by_year
        article_years.each do |year|
          haml_tag :li do
            haml_tag :a, :id => "#{year}"
            haml_tag :h2, year
            haml_tag :ol do
              articles = Page.find_articles.select { |a| a.date.year == year }
              list_articles(articles)
            end
          end
        end
      end
    end
  end
end

Creating an /archives page

We’ve just defined a new Ruby method called archive_by_year that we can call from within a page to insert a list of all the articles on the site. Let’s create a new file called content/pages/archives.haml and add the following Haml to it:

%h1 Archives

%p
  Here's the full list of all the posts on the blog. I hope you enjoy
  browsing through them...

%ol.archive
  - archive_by_year

In case you haven’t used it, Haml is a clean and simple way of writing HTML. Nesta will convert Haml to HTML for you when the page is served. Any line in a Haml file that starts with a hyphen will be treated as Ruby, so our archive_by_year method is run and the HTML it produces is inserted inside an <ol> tag.

Before we load the page, let’s just add a bit of CSS to style our list of articles. You can style it however you like, but I tend to use something simple like this:

ol.archive {
    list-style: none;
}

ol.archive ol {
    list-style: disc;
}

If you’ve written your own styles for your site you’ll no doubt know which file to add those styles to. If you’re using the standard theme you’ll be able to add it to a file called views/local.scss and it’ll be loaded automatically.

If you fire up a local web server (e.g. with shotgun) you should be able to see a list of all your blog posts at /archives.

Adding navigation links

To make it easier for people to browse your archives you could add a few links to the sidebar. I’m assuming you’re using the standard theme here; you may need to adapt the code that follows so that it works with your site’s design, but you’ll get the idea.

First, create a template that will render a list of links to the years in which we’ve published articles. Put this Haml in views/years.haml:

%nav.archive
  %h1 Articles by year
  %ol
    - article_years.each do |year|
      %li
      %a{ :href => "/archives##{year}" }= year

Let’s style it with this CSS (add it to local.scss again, or wherever you put your CSS for styling the /archives page):

nav.archive ol {
    list-style: none;
}

Now you just need to render the years.haml template in a suitable place in your sidebar. If you’re using a theme that has a sidebar.haml template you can copy the sidebar.haml file to your views folder, and edit it so it looks something like this:

#sidebar
  = haml :categories, :layout => false
  = haml :years, :layout => false

If you’re not sure where to find a sidebar.haml file, these commands may help (run them from within your site’s folder):

$ ls `bundle show nesta`/views
$ mkdir -p views
$ cp `bundle show nesta`/views/sidebar.haml views

Nesta 0.9.13 released

2012-03-04T00:00:00+00:00

Version 0.9.13 has been released. New features include support for Erb templates (in the views folder only, not for pages) and a nesta edit command that makes it easier to edit your site. Etag support is enabled in new projects.There have also been a few internal API tweaks to support the plugins that are starting to spring up. Two view helper methods (url_for and base_url) have been removed.

There have been a few contributors to this release (thanks all). Max Sadrieh has been particularly helpful by digging through the list of outstanding issues, submitting patches, and generally getting stuck in. :-)

Upgrading

If your project (or theme) contains any templates that use the url_for or base_url helpers, you’ll need to replace them with a call to the url helper from Sinatra. It’s automatically available to you within your templates, and takes a path. For example:

%a{ :href => url(page.path) }= page.heading

If you’ve copied the atom.haml or sitemap.haml files from the default set into your views folder, they’ll need updating (if you haven’t actually changed them just delete them, and Nesta will find them in the gem itself).

The changes

Here’s the CHANGES file with the full list of updates:

The nesta script has a new command; edit. You can pass it the path to a file within your content/pages folder and it will open the file in your default editor (as set by the EDITOR environment variable).
The nesta script has a new option; --bash-completion. Run nesta with this option and it will print some Bash that will configure command line completion for the nesta command.

You can type nesta edit <TAB> and Bash will complete the names of the files in your content/pages directory. :-)

Installation instructions at the top of the Bash script.
Nesta can now be mounted cleanly at a path, rather than at a site’s root, and assets and links will be served correctly. (Max Sadrieh, Graham Ashton)
The default config.ru file that is generated when you create a new project now enables Etag HTTP headers. (Max Sadrieh)
Two helper methods have been removed; url_for and base_url. Use Sinatra’s url helper instead. They would have been deprecated rather than removed, but if you try and load Nesta’s helpers in a Rails app url_for breaks Rails’s rendering. (Max Sadrieh, Graham Ashton)
The current_item? helper has been created in Nesta::Navigation. You can override it to implement your own logic for determining whether or not a menu item rendered by the menu helpers are considered to be “current”. (Chad Ostrowski)
The Page class has a new method; body_markup. It can be overridden by a plugin, and is used by the foldable plugin. (Micah Chalmer)
The FileModel class has a new method; parse_metadata. It can be overriden by plugins that implement an alternate metadata syntax. Used by the yaml-metadata plugin.
Erb templates in your ./views folder, or in a theme’s folder, will now be found when you call Sinatra’s erb helper method.
config.yml can now contain Erb (and therefore inline Ruby), which will be interpreted when loaded. (Glenn Gillen)
Extended the nesta command to support new commands that could (for example) be added by a plugin. The class to be instantiated within the Nesta::Commands module is determined from the command line argument (e.g. nesta plugin:create will instantiate the class called Nesta::Commands::Plugin::Create).
Bug fix: Don’t crash if a page’s metadata only contains the key, with no corresponding value. You could argue this wasn’t a bug, but the error message was difficult to trace. See #77.
Bug fix: Summaries on Haml pages were not marked up as paragraphs. See #75.

I really hope I haven’t forgotten anybody. Let me know if I have and I’ll update the post/CHANGES file…

Setting up rack-codehighlighter

2012-02-27T00:00:00+00:00

If you write about software, you can make code look more attractive by adding syntax highlighting to your pages. Nesta is a Sinatra app (and is therefore built on top of Rack), which makes it easy to setup syntax highlighting with the rack-codehighlighter gem.

Installing the gem

Before you can highlight any code, you’ve got a decision to make. There are several highlighting libraries available to you

Add the rack-codehighlighter gem and your preferred highlighting library (I’m using coderay in this example) to your Gemfile and run bundle:

$ echo 'gem "coderay"' >> Gemfile
$ echo 'gem "rack-codehighlighter", :require => "rack/codehighlighter"' >> Gemfile
$ bundle

Now edit your project’s config.ru file, as outlined in the rack-codehighlighter README file. Because I’m using coderay the bottom of my config.ru file now looks like this:

use Rack::Codehighlighter, :coderay,
    :element => "pre>code", :markdown => true

run Nesta::App

The :element and :markdown options that I’ve set in this example work well if your content is written in Markdown; if you’re using Textile you’ll want to tweak the setting (see the README).

Now start your app up in development mode, add a block of source code to one of your web pages, and tell the highlighter what syntax it is. Something like this should do it:

:::ruby
def hello
  puts "Hi!"
end

Reload the page. If :::ruby has been removed from the HTML then the highlighter is working – if you look at the source you’ll see that your code has been wrapped in span tags.

Now you need some CSS to make it look pretty.

Adding some colour

If you’ve decided to use Ultraviolet it looks as though you can choose a theme and tell Rack::Codehighlighter to deal with it for you. I haven’t investigated that yet – see the README for notes on Ultraviolet.

CSS styles for Coderay

If you’re using Coderay you’ll need to provide your own CSS. I’m too lazy for that, but luckily some kind souls have shared their CSS with the rest of us. I like the GitHub styles and the RailsCasts colours.

Update: Since I first wrote this article, coderay appears to have updated the CSS class names that it uses to highlight code, and those themes don’t work any more. If you’d like to use them, make sure that you tell Bundler to load an earlier version of coderay (I’m using 0.9.8 successfully, and I’m not sure when the CSS class names were changed).

If you’re using a Nesta theme…

Themes load their CSS from their own views folder (e.g. themes/slate/views), but if you put a stylesheet in your site’s views folder Nesta will load that instead.

So we’re going to pull a neat trick, and get Sass to include our stylesheet at the end of the theme’s default CSS. Start by making a copy of the theme’s Sass file:

$ mkdir -p views
$ cp themes/slate/views/master.sass views/

Now get your Coderay CSS and store it in a .scss file:

$ curl https://raw.github.com/pie4dan/CodeRay-GitHub-Theme/master/coderay.css \ 
  > views/coderay-github.scss

Finally, get Sass to import the styles into the main stylesheet:

$ echo '@import "coderay-github"' >> views/master.sass

You should be all set. Try reloading your page and see if your code is in colour.

If you’ve designed your own site…

Download the source for one and put it in public/css:

$ mkdir -p public/css
$ curl https://raw.github.com/pie4dan/CodeRay-GitHub-Theme/master/coderay.css \ 
  > public/css/coderay-github.css

Edit your layout template and load the CSS with a <link> tag. You should be good to go…

Resources

The rack-codehighlighter gem
RailsCasts episode 207 from Ryan Bates

Using an unreleased version of Nesta

2012-01-16T00:00:00+00:00

Let’s say that there’s a cool new feature of Nesta you want to try, that was added to Nesta more recently than the last version was released. With Bundler there’s an easy way to use the bleeding edge version of Nesta for your projects.

You’ll need to replace the line in your Gemfile about Nesta with the following:

gem "nesta", :git => "git://github.com/gma/nesta.git"

And then run:

$ bundle install

Voilà, you are now running the latest development version of Nesta.

Maybe that particular feature you want is in a specific branch other than master. You can specify which branch you want, for example:

gem "nesta", :git    => "git://github.com/gma/nesta.git",
             :branch => "gem-plugins"

In fact, when we pass the :git option only, the master branch is assumed.

Note also that this can be used to specify your own branch or repository, so that Nesta can have all the features you built. For example:

gem "nesta", :git => "git://github.com/your-name/nesta.git"

Be warned that this requires a .gemspec file in your project folder. If you don’t have one you should pass a version number to Bundler so that it can resolve dependencies, as in:

gem "nesta", "0.9.11", 
             :git => "git://github.com/your-name/nesta.git"

More details and further options can be found on the Bundler web site.

Making an Art Directed blog

2011-09-22T15:00:00+00:00

When Geoffrey Grosenbach released the new PeepCode blog it made quite a splash. Each article is beautifully presented with its own unique design. When he wrote about how he’d based his blog on Nesta I got lots of questions asking how to achieve something similar.

Smashing Magazine have also written about blogazines, showcasing some impressive designs.

It’s been fairly easy to achieve something similar with Nesta for a while, but it’s now easier than ever with the blogazine plugin.

Installing the plugin

Open a terminal and navigate to your site’s folder. Then add the nesta-plugin-blogazine gem to your Gemfile:

$ cd path/to/site
$ echo 'gem "nesta-plugin-blogazine"' >> Gemfile
$ bundle

The plugin provides a way for us to load a different CSS file for each page.

To use it we need to modify your site’s layout template.

Creating your layout template

If you’ve already customised the design or have installed a theme, skip ahead to the next section.

If your site uses Nesta’s default theme you’ll need to create a copy of the themes templates in a local ./views folder. This will do it:

$ cd path/to/site
$ mkdir -p views
$ cp $(bundle show nesta)/views/* views

Updating the layout

Open your layout template in an editor (e.g. views/layout.haml or themes/slate/views/layout.haml) and change the line that loads the main CSS file, setting the name of the stylesheet to #{page_design}:

%link(href="/css/#{page_design}.css" media="screen" rel="stylesheet")

By default page_design will return “master” – if your site’s default stylesheet has another name you can specify that instead:

%link(href="/css/#{page_design('application')}.css" media="screen" rel="stylesheet")

Your site should still be working as before, but is now ready for you to start adding your designs…

Creating a new design

For each new design, add your CSS to a new Sass or SCSS file in the views folder. I’m going to assume that you’ve created a new design in views/trees.scss.

To use your design, open the blog post that you want to apply the design to and set the ‘Design: trees’ metadata at the top of the file:

Design: trees
Date: 10 Sep 2011
Categories: blog/nature

# Deciduous woodland

Your blog post starts here...

When you reload the page Nesta should serve trees.css instead of the site’s default stylesheet.

Tip: You can share common styles between multiple designs using Sass’s ability to import other Sass files. At the top of trees.scss you could write:

@import "master"

// Styles specific to the trees design go here...

If your page design is significantly different to the other pages on your site and you need to serve different HTML, you can change the template and layout that are used on the page.

Useful resources

About the PeepCode blog (Geoffrey Grosenbach)
The Death of the Blog Post (Smashing Magazine)
The Pros and Cons of Art-Directed Blogs (Webdesigner Depot)

Nesta 0.9.11 released

2011-09-22T00:00:00+00:00

Version 0.9.11 has been released.

Nesta now uses Ryan Tomayko’s Tilt library to manage the rendering of Markdown and Textile files inside your content/pages folder. That means you can choose which Markdown processor is used to render your content. The default processor is now RDiscount (in previous versions it was Maruku).

Trailing slashes are now stripped off all URLs (see issue 60).

There is also a new metadata key called ‘Articles heading’ (see the docs).

Upgrading

If you’re upgrading from 0.9.7 or later, just update your Gemfile and re-run bundle.

$ sed -i '' -e '/nesta/ s/0.9.[0-9]/0.9.11/' Gemfile
$ bundle

If you’re upgrading from an earlier release you’ll also need to get yourself a new copy of the config.ru file from the template file in the gem:

$ cp $(bundle show nesta)/templates/config.ru .

If you’d like to continue to use Maruku to process your Markdown, see the documentation on how to switch back to Maruku.

The changes

Here’s the CHANGES file with the full list of updates:

Use Tilt to render the Markdown, Textile and Haml in content/pages. RDiscount is now the default Markdown processor. To continue using Maruku add it to Gemfile and call Tilt.prefer Tilt::MarukuTemplate in your app.rb file.
Remove trailing slashes from all URLs, redirecting to the URL without the slash. See ticket #60 on GitHub.
Added the ‘Articles heading’ metadata key. 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 you set the ‘Articles heading’ metadata Nesta will allow you to override the entire heading for a given page.
Bug fix: require nesta/plugin automatically on load. The Nesta::Plugin.register method is called by plugins as soon as they are loaded, so we need to make it available. In 0.9.10 this method wasn’t available until too late.
Bug fix: Minor updates to the files generated by nesta plugin:create.
Bug fix: Don’t allow retrieval of the contents of any file within the content folder by crafting a relative path containing the string ‘../’ (Louis Nyffenegger).

Using a different Markdown processor

2011-09-21T00:00:00+00:00

There are a handful of Markdown processing libraries available for Ruby, each with different advantages and features. Since version 0.9.11, Nesta uses Ryan Tomayko’s Tilt library to work out which processor to use when rendering a file within your content folder.

At the time of writing, Tilt knows about the following Markdown processors:

Tilt will try to load a Markdown processor in the order defined above. If it can’t find Redcarpet, it’ll try RDiscount, then BlueCloth, etc.

RDiscount is used in Nesta by default, as it is the only one that is included automatically as a Nesta dependency (i.e. it is the only one that is likely to be available in your project so Tilt is likely to find it first).

Installing other processors

To change the default (e.g. to BlueCloth), add your chosen processor’s gem to your Gemfile and re-run bundle:

$ cd path/to/project
$ echo 'gem "bluecloth"' >> Gemfile
$ bundle

The other gems that you might want to install are called redcarpet, kramdown and maruku (the rdiscount gem is already installed).

Configuring Tilt

Then tell Tilt that you’d rather it used BlueCloth by adding the following line of Ruby code to the app.rb file within your project (if you don’t have an app.rb file, just create it):

Tilt.prefer Tilt::BlueClothTemplate

The full list of class names that you might want to use in place of BlueClothTemplate is:

Tilt::RedcarpetTemplate
Tilt::RDiscountTemplate
Tilt::BlueClothTemplate
Tilt::KramdownTemplate
Tilt::MarukuTemplate

This post may go out of date as the Markdown processing support in Ruby evolves. You can always check the list of class names at the bottom of tilt.rb to review current options…

Adding author biographies to articles

2011-09-10T00:00:00+00:00

Imagine for a moment that multiple people contribute to your site’s blog. In return for providing you with content, authors expect a bit of publicity and a link back to their own site from the bottom of their article.

Once a blogger has written a couple of posts for you you’ll find yourself wanting to re-use their biography, photo and links on each of their articles. What’s the best way to do this with Nesta?

There are a couple of approaches you can take, but I really like the way that Adam and Wynn are doing it on thesassway.com.

Here’s what you do (as Adam explained it to me):

Add some custom metadata to each blog post that identifies the author.
Create a Haml template for each author in your ./views folder that contains the HTML for their bio, link and photo.
Update your page template (e.g. views/page.haml) and get it to check whether the page has an author. If an author is defined, render the relevant author’s bio.

So your blog post might look this:

Author: Adam Stacoviak
Date: 28 August 2011
Categories: adam-stacoviak, projects
Summary: Twitter’s “Bootstrap” is a HOT topic…

# Sass Twitter Bootstrap

Twitter’s “Bootstrap” is a HOT topic…

Then add the markup for the author’s bio to a new template in the views folder. Give the template a name that can be derived from the author’s name. I’d recommend converting it to lower case and replacing spaces with underscores, to give views/adam_stacoviak.haml.

Let’s add a custom helper to app.rb that will render our author’s template for us. Define author_biography in your app.rb file:

module Nesta
  class App
    def author_biography(name = nil)
      name ||= @page.metadata('author')
      if name
        template = name.downcase.gsub(/\W+/, '_').to_sym
        haml template, :layout => false
      end
    end
  end
end

In your views/page.haml file add a snippet of Haml where you’d like to display the bio (it might make sense to insert it after the line that calls @page.to_html):

= author_biography

If you’re wondering what that optional name argument to author_biography is there for, read on…

Create a page for each author

If you take another look at the metadata for the example post above you’ll see that the post has been added to the adam-stacoviak category. That means that it will automatically be listed on a page at the URL /adam-stacoviak. Wouldn’t it be nice if you include the bio at the top of that page? The easiest way to do it would be to create /adam-stacoviak as a Haml page in content/pages and include the biography like this:

Category: authors

%h1 Adam Stacoviak

= author_biography('Adam Stacoviak')

Nesta will automatically insert all the pages in the author’s category for you, beneath the bio.

Nesta 0.9.10 released

2011-09-09T00:00:00+00:00

Version 0.9.10 has been released. New features include support for extending Nesta with plugins (which are distributed as Ruby gems) and the ability to mark a page as draft (which will hide it on your production site).

See the plugin documentation for information on how to write and share plugins. The draft functionality has been implemented with a new metadata key called flags, which allows you to add boolean settings to your pages. You can then check a page’s flags in your template and modify the web page accordingly.

Upgrading

If you’re upgrading from 0.9.7 or later, just update your Gemfile and re-run bundle.

$ sed -i '' -e '/nesta/ s/0.9.[0-9]/0.9.10/' Gemfile
$ bundle

If you’re upgrading from an earlier release you’ll also need to get yourself a new copy of the config.ru file from the template file in the gem:

$ cp $(bundle show nesta)/templates/config.ru .

The changes

Here’s the CHANGES file with the full list of updates:

Load Nesta plugins from gems. Any gem whose name begins with nesta-plugin- can be used in a project by adding it to the project’s Gemfile beneath the gem "nesta" line. New plugins can be created with the nesta plugin:create command.
Mark pages as draft by setting a flag. Draft pages won’t be shown in production, but will be visible on your local copy of your site (as it’s running in “development”).
Upgraded Sinatra to version 1.2.6. Upgraded other dependencies to latest compatible versions.
Bug fix: The stylesheet helper method assumes that you’re using the Sass rendering engine by default, which allows it to find .sass files within the gem if no matching files are found locally.