isabella232 / jekyll_pages_api

a Jekyll Plugin that generates a JSON file with data for all the Pages in your Site

Jekyll Pages API

Jekyll Pages API is a Jekyll Plugin gem that generates a JSON file with data for all the Pages, Posts, Documents (i.e. "collections") and StaticFiles in your Site. Jekyll, if you're not familiar, is a static website generator written in Ruby.

Usage

Add this line to your application's Gemfile:

group :jekyll_plugins do
  gem 'jekyll_pages_api'
end

If you're creating a new Gemfile in your Jekyll project, make sure to include a source at the top:

source 'https://rubygems.org'

And then execute:

bundle
bundle exec jekyll serve

You can then see the generated JSON file at http://localhost:4000/api/v1/pages.json, which will look like this:

{
  "entries": [
    {
      "title": "18F Hub",
      // the page path
      "url": "/",
      // the content of the page, with the HTML tags stripped and the whitespace condensed
      "body": "18F is a digital services team within GSA...",
      "meta": {
        // all the frontmatter for the page
        "title": "18F Hub",
        "url": "/",
        "layout": "page",
        "permalink": "/",
      }
    },
    // ...
  ]
}

This endpoint will be re-generated any time your site is rebuilt.

Skipping the index

The Jekyll Pages API Search plugin uses this plugin to build a search index. Add skip_index: true to the front matter of any documents you wish to exclude from this index.

Running standalone

If you wish to generate a pages.json file when using a site generation tool other than Jekyll, you can run the jekyll_pages_api executable as a post-generation step. Run jekyll_pages_api -h for instructions.

Developing

Important Note: This gem uses the Appraisal Gem to ensure that it's tests pass against all supported versions of Jekyll. It uses the appraisal command - you can read more in the documentation.

• Run bundle to install any necessary gems.
• Run bundle exec rake -T to get a list of build commands and descriptions.
• Run bundle exec rake spec to run the tests.
• Run appraisal install to install the correct Jekyll dependencies.
• Run appraisal rake spec to run all of the appraisals.
• Run bundle exec rake build to ensure the entire gem can build.
• Commit an update to bump the version number of lib/jekyll_pages_api/version.rb before running bundle exec rake release.

While developing this gem, add this to the Gemfile of any project using the gem to try out your changes (presuming the project's working directory is a sibling of the gem's working directory):

group :jekyll_plugins do
  gem 'jekyll_pages_api', :path => '../jekyll_pages_api'
end

See also

Additional means of turning your site content into data:

• Jekyll's jsonify filter
• jekyll-git_metadata
• jekyll-rss
• jekyll-sitemap
• Reading the YAML frontmatter of the source files
• Scraping the HTML pages themselves