Skip to content

Latest commit

 

History

History
138 lines (95 loc) · 5.19 KB

README.md

File metadata and controls

138 lines (95 loc) · 5.19 KB
Raw

rism-theme

Welcome to your new Jekyll theme! In this directory, you'll find the files you need to be able to package up your theme into a gem. Put your layouts in _layouts, your includes in _includes, your sass files in _sass and any other assets in assets.

To experiment with this code, add some sample content and run bundle exec jekyll serve – this directory is setup just like a Jekyll site!

TODO: Delete this and the text above, and describe your gem

Installation

Add this line to your Jekyll site's Gemfile:

gem "rism-theme"

And add this line to your Jekyll site's _config.yml:

theme: rism-theme

And then execute:

$ bundle

Or install it yourself as:

$ gem install rism-theme

Configuring the footer

The footer can be configured to display social media links and sponsors. For example:

follow_us:
  facebook: https://www.facebook.com/RISM.info/
  twitter: https://twitter.com/RISM_music
  youtube: https://www.youtube.com/channel/UCWLRkiqVuq8BrYbCArubi_w
sponsors:
  - url: https://www.musicology.org/
    logo: logo_ims.png
  - url: https://www.iaml.info/
    logo: logo_iaml.png

Logo images have to be placed in ./images/footer

Enable website search

Website search can be enabled with the rism-website-indexer plugin. The theme includes some scripts and templates for the website search.

The website search script included in the search-lunr.html template expects:

  • a /pages.json file that is generated by the rism-website-indexer plugin
  • a /index.json file that is generated by the build_index.js node script from the /pages.json file - see the rism-website-indexer documentation on how to run the script.

To enable website search add to the _config.yml file:

enable_search: true

Enabling search adds a link to the search page on pages with a hero_height: is-medium and adds a search box in the navigation bar the for pages with a hero_height: is-small.

Pages of the site can have additional frontmatter indexing directives:

  • search_exclude: true
    The page will not be included in the search index.
  • no_search_box: true
    No search box will be shown in the navigation bar - useful for the search page when it includes a search sidebar.
  • index_all_lang: true
    The page will be indexed for all languages - by default, a page is indexed only in its original language.

The website search page is expected to have a permalink /search.html. A /search.en.md file will as simple as:

---
title: RISM
layout: default
hero_height: is-small
lang: en
search_exclude: true
no_search_box: true
sidepanel: "sidepanels/search-lang"
permalink: /search.html
---

{% include search-lunr.html %}

No translation of the search page is required because the search-lunr.html page looks at the site.active_lang value.

The sidepanel/search-lang is a template included in the theme. It add a sidebar with the search input field and a language selection list. The frontmatter entry can be omitted. In that case, no language filtering will be available, which can be desirable for website in one language. It is recommended also to omit the no_search_box entry in that case because otherwise no search field will be available from the search page.

Labels

Label translations for the search are not included in the theme but are expected to be given in the _data/locales.yml file of the website. The list of keys are:

  • search-title
  • search-results
  • search-input
  • search-results-count
  • search-no-result
  • search-no-query
  • search-tip
  • search-lang-label
  • search-lang-any
  • search-category-label
  • search-category-any

The search-tip can be omitted.

Limiting posts categories

A filter by post category can be added to the sidebar by adding to the _config.yml file:

enable_search_posts: true

The list of categories and the label translations in the search sidebar will be pulled from the _data/categories.yml file.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hello. 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.

Development

To set up your environment to develop this theme, run bundle install.

Your theme is setup just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in rism-theme.gemspec accordingly.

License

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