galliani / jekyll-airtable

Jekyll plugin to easily integrate with Airtable

Jekyll::Airtable

This gem enables you to easily integrate Airtable with Jekyll site and use it as a database. Everytime the Jekyll build is triggered, the gem would automatically send API request to the Airtable base and tables you specify from the environment variable and then store the records as collections, grouped according to the table names.

Installation

Add this line to your Jekyll site Gemfile:

gem 'jekyll-airtable'

And then execute:

$ bundle install

Usage

1. Because you will have to mention/use your API key, it is VERY RECOMMENDED to use dotenv so you do not have your API key lying around in plain sight.

gem 'dotenv'

run bundle install again

2. Add this to your repo .gitignore (create one if does not exist):

.env

3. Copy the .env.example in this repo to the root of your project, rename it to .env.
4. Set your Airtable API Key in the .env

AIRTABLE_API_KEY='your_airtable_api_key'

5. You need to add a custom plugin to get the dotenv to work, you do this by creating a folder _plugins (if does not exist already) inside your Jekyll repo
6. Inside the /_plugins , create a file called "environment_variables_generator.rb", with this as the content:

# Plugin to add environment variables to the `site` object in Liquid templates
require 'dotenv'

module Jekyll
  class EnvironmentVariablesGenerator < Generator
    priority :highest
    
    def generate(site)
      Dotenv.overload
      site.config['env'] = Dotenv.overload

      site.config['AIRTABLE_API_KEY']   = ENV['AIRTABLE_API_KEY']
    end
  end
end

Now the secret keys can be accessed by Jekyll without being visible to the public.

7. Now, you need to declare and hook the plugins in the config.yml

plugins:
  - jekyll-airtable
  - environment_variables_generator

airtable:
  enable_sync: true
  base_uid: 'appp7C1MblPCnMePn'
  tables:
    - name: 'Use Cases' 
    - name: 'Whitepapers'    
    - name: 'Quotes'
      long_text_columns:
        - 'column name'

8. Finally, you can execute the plugin using sh bundle exec jekyll serve or sh bundle exec jekyll build

For production, you also have to set those keys and values.

9. You then need to set the collections on the _config.yml so that Jekyll recognizes them. The snippets below here are taken from https://github.com/galliani/airbase/blob/master/_config.yml. The collections on that repo are "use_cases", "whitepapers", and "tutorials", taken from the Airtable of "Use Cases", "Whitepapers", and "Tutorials" respectively.

collections_dir: collections
collections:
  use_cases:
    output: true
  whitepapers:
    output: true

defaults:
  - scope:
      type: "whitepapers"
    values:
      layout: "page" # any jekyll layout file you already have in the _layouts that you want to use for this collection type.

Conventions

There are a number of "enforced" conventions you have to know and can take advantage of.

1. By default, the slug of the record (which is the file name) come from this sources, in order of priority: 1) The column labelled 'Slug' / 'slug' in your Airtable table, 2) The primary key of each row (the first column on each table), 3) or the Airtable UID of the record. So if you want to set each record's slug manually, you can do so by creating slug column in your Airtable table.GOTCHA: Should slugs that are derived from priority 1 and 2 are both longer than 100 char, then it will automatically use the Airtable UID.

2. Attachments are not copied into your Jekyll repo but their informations, such as url and so on, will be stored in "data/airtable/attachments.yml" folder, if none exist before, this plugin will automatically create it for you.

3. Long text with paragraphs are now supported.

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/galliani/jekyll-airtable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Jekyll::Airtable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

jekyll-airtable's Issues

undefined method `length' for nil:NilClass

love this plugin. Everything worked fine. But now, when the plugin syncs with airtable I get the following error:

jekyll 3.8.0 | Error: undefined method length' for nil:NilClass`

The the sync stops. And it seems to happened while the attachments get updated. Because all the new attachment won't sync. The listing are syncing fine.

I dont know if I have some buggy content in my airtable or if it is a bug. Or is there a limit on how many attachments are allowed?

###UPDATE####
the problem was: there was a blank record in the airtable. After I deleted it everything synced fine again!

Collection generator creates filenames with underscores

When I construct a file name in a template using the slugify filter, phrases become hypenated-like-so, but the plugin creates filenames with underscores instead. Could this be a setting?

Feature or documentation request: relational collections

It's been a while since I had a chance to work with this plugin and I must thank you again for putting it together.

One thing I'd like to do is to relate items in collections with other collections.

For example: "product x" in the "products" collection could link to "manufacturer x" in the "manufacturers" collection, and the latter "manufacturer x" page could list all products associated with it.

Right now the UIDs can probably make this possible but I'd like to auto-generate file names for the finished site from the titles of each entry. I did try creating a slug column in Airtable but it doesn't appear to create what I expected. Your thoughts would be welcomed!

Access attachments.yml within collection loop

Is it possible to access attachments within a collection loop? I am trying to do something like this, but am having no luck. Thanks!

<ul>
    {% for author in site.authors %}

        <h5>{{ author.name }}</h5>
        {% assign photo = site.data.airtable.attachments[author.image] %}
        <img src="{{ photo.url }}" />

    {% endfor %}
</ul>