A Jekyll static site generator theme for building lightweight audio tours for exhibitions or museums.
This template is built on top of the Jekyll new theme by Joel Glovier. While it is reusable in its current form, it was purpose built for the Scorsese Exhibition at ACMI. Take a look at a live version, and view the Scorsese Audio Guide. For a demo of this version, take a look at the Github pages hosted demo: http://acmilabs.github.io/static-museum-audio-guide/welcome/
Some image editing / Photoshop skills will be required to build a finished guide. Parts of the theme (such as the welcome page) are just plain old HTML and will need to be customised for your guide.
The audio guide features the following main pages:
/welcome- an onboarding page, using Slick JS to get users started with the audio guide./- a menu with headphone icons to begin using the guide./stops/1- an individual audio guide stop, with slide-down menu, hero images in a carousel, and fixed footer audio player.
The guide will work best with 128kbps 16-bit 44.1khz MP3 files.
There is also a simple page at /connected as a landing page if you are using Captive Network WiFi pages. Redirect post login pages to this page, and the anchor tags with target="_system" should make the links open in Safari on iOS devices.
- Follow the instructions on the Jekyll site to install Jekyll static site generator on your local dev machine.
- Clone this repo and run
jekyll serve, to see a sample version of the web app. - In the
stopsdirectory, create numbered markdown files for all the stops in your audio guide. - Each audio guide stop is just a page in Jekyll terms, using a layout called
episode. - Meta-data should be added to the top of each audio guide stop as follows:
layout- this should be set toepisodepermalink- the default structure is/stops/1(replace the number with the desired permalink)type- set this tostop- type is used for generating the slide down menussection_title- this appears at the top of each stop pagetitle- this is a sub-heading, but is typically the name of the actual object in the exhibition, and is used as the title of the page.page_rank- this is used to order the stops in the menu and slide-down menustop_id- if you wanted, you could give the stop a different ID number to its page rank, but you should probably keep it the same as the permalink and page_rank.audio_file- just the filename and extension of the MP3 file to playhero_images- an array ofpathandalt_textvalues for the hero image on the audio guide stop page. Multiple images will appear in an image carousel (using Slick JS). Thepathshould just be the image filename and extension. The folder location is set in the main site settingsconfig.yml. Good image settings for this are 512 x 341 pixels (1.5:1 aspect ratio) JPEG at 50 - 60% compression.
- Update
config.ymlwith settings for your particular guide. You can use the default settings, but be sure to update thetitle,description,urlandtwitterusernames for your site. If you want to change the folder structure for the MP3s or hero images, you can do that here. - Create a new logo and save it over
/assets/img/logo/audio-guide.png. - Replace the footer logo and link with your own organisation or partner logos in
_includes/footer.html. - Update
/assets/img/meta/og-image.jpgwith an image you'd like to have appear when the site is shared on social media. (This is used for Open Graph tags, pulled by Facebook and other sites). - To change colour scheme, update the variable
$brand-colorincss/main.scsswith your main colour. Most of the other colours in the web app will be calculated from this one. - Add Font import or @font-face statements to
_sass/_fonts.scssand update$base-font-familyin_css/main.scssto swap fonts. - Once you're happy with your content and have updated all styling and branding above, launch your site locally with
jekyll serveat the command line. Navigate to a stop in the audio tour and take screenshots at mobile resolution. - Update the images in
assets/img/welcomewith these screenshots from your own web app. - In
_layouts/welcome/htmlupdate the mark-up of the welcome pages to give an overview to your web app. - Once you're happy with your audio guide, drop in your own Google Analytics or Google Tag Manager snippet into
_includes/tagmanager.html.
Each time you update the JS or CSS files, you may wish to update version_number in config.yml. This is appended a query string to the CSS link and JS script tag in the Head element for cache busting.
Since this is just a straightforward Jekyll site, you can deploy it straight to Github pages. Follow the instructions here: https://help.github.com/articles/using-jekyll-as-a-static-site-generator-with-github-pages/
If using Firebase, set the site directory as '_site' and be sure to run jekyll build before pushing the site to Firebase.
If using TeamCity and Octopus for running builds and deployments, a .nuspec file is included here, to specify the _site folder as the contents of the package.
This site includes markdown.rb in the _plugins folder, by Tomotaka Sakuma. The gist on Github is located here: https://gist.github.com/tmtk75/1408402. We found out about it from this post: http://wolfslittlestore.be/2013/10/rendering-markdown-in-jekyll/
The above snippet allows you to easily use markdown includes in the site, however it breaks support for Github pages, so we've removed useage from this repo. In the index.html page for example, you could use {% markdown overview.md %} to include the markdown text in overview.md without having to write HTML. The on boarding pages could also be refactored to use this.
When the site is added to the homescreen on iOS, we use a code snippet from iosweblinks (original author Kyle Barrow) to get links to remain in the web app view rather than opening up Safari.
To check whether or not to make the player fixed position to the bottom of the screen, we borrow the $.support.fixedPosition check from jQuery mobile, which doesn't do a true check of the feature, but eliminates known browsers that have issues with that CSS property. This enables fallback to an in-flow position for the player, which makes it sit at the very bottom of the page. We've placed a minimal version of the check in the head of the page, but the full jQuery mobile snippet is here: https://github.com/jquery/jquery-mobile/blob/master/js/support.js
Most of the web app (aside from audio!) works without JavaScript, and we've tried to keep to a progressive enhancement approach as much as possible. The following JS libraries have been included here, each is covered by their own MIT license also in the repo. If you're extending this project, you may wish to switch to CDN copies, or concatenate and minify your libraries.
In this repo, we've chosen to keep these libraries as local assets so that running jekyll serve or jekyll build from the command-line is as simple as possible. However, you may wish to switch to loading these libraries from a package library instead.
Read the ACMI Labs blog posts covering this project:
The Static Museum Audio Guide theme is released under the terms of the MIT license. Included JS libraries are covered by their own licenses, included in this repo.