Middleman > Integrating with Middleman

    Integrating with Middleman

    DatoCMS offers Middleman plugin that makes it extremely convenient to use content stored in your administrative area inside your website views.

    Disclaimer This guide assumes you already know what Middleman is and how it works. If you need some help getting started with Middleman, you can read the official Middleman documentation.

    Installing the plugin

    Inside your Middleman project, you can install the middleman-dato gem tool running these commands:

    $ echo 'gem "middleman-dato"' >> Gemfile
    $ bundle install

    Once installed, you can activate the plugin in your config.rb:

    activate :dato, live_reload: true
    # enable livereload on development
    configure :development do
    activate :livereload

    The plugin reads your DatoCMS API token from a .env file (just make sure not to publish it on Github):

    $ echo '.env' >> .gitignore
    $ echo 'DATO_API_TOKEN=abc123' >> .env
    $ bundle exec middleman server

    You can find your API token in the Admin area > API tokens section:

    Published vs latest versions

    If you are working on development/staging environment, you might want to preview the latest version of records instead of the published one. In this case, you can activate the preview flag:

    activate :dato, preview: true

    Reading from a sandbox environment

    To explicitely read data from a specific environment and not from the primary one you can use the environment option:

    activate :dato, environment: "my-sandbox-environment"

    Accessing DatoCMS content

    Once the plugin is activated, an object called dato will be available in your Middleman views to access content coming from your administrative area:

    <!-- source/index.html.erb -->
    <h1><%= dato.homepage.title %></h1>

    The same object is also available in your config file. To create multiple pages starting from a collection of DatoCMS records, you can use Middleman proxy pages:

    # config.rb
    # activate middleman-dato plugin
    activate :dato, live_reload: true
    configure :development do
    activate :livereload
    # due to how middleman 4 collections work (http://bit.ly/2jHZTI9),
    # always use `dato` inside a `.tap` method block, like this:
    dato.tap do |dato|
    # iterate over the "Blog post" records...
    dato.blog_posts.each do |article|
    # ...and create a page for each article starting from a template!
    proxy "/articles/#{article.slug}.html", "/templates/article.html", locals: { article: article }
    # tell Middleman to ignore the template
    ignore "/templates/article.html.erb"
    <!-- source/templates/article.html.erb -->
    <h1><%= article.title %></h1>
    <% article.categories.each do |category| %>
    <li><%= category.name %></li>
    <% end %>
    <%= article.content %>

    Run bundle exec middleman server and enjoy!

    Obviously, that's just a quick tour: you can learn all the details about how to access your records inside your views and config file in the following sections.

    We use cookies to enhance the user experience. Do you consent their use in accordance with our cookie policy?