Jekyll Tutorials for Samvera Connect 2018

jekyll_tutorials_for_samvera_connect_2018.md

Samvera Connect 2018 - Documentation with Jekyll workshop

This page contains some exercises and discussion topics for using Jekyll to help build and maintain samvera.github.io, a documentation website for the Samvera community.

Expectation Management: We are not experts in Jekyll, but we're here to tell you what we know after playing around with it for the past year or so.

Get the latest code (3 min)

1. Go to https://github.com/samvera/samvera.github.io
2. Clone the repo.
3. cd samvera.github.io
4. git pull

Create a page (10 min)

Here we'll create a new page called "Help Improve This Site".

1. Find the ticket, assign someone (a participant), and move the ticket in the project board.

2. Create branch git checkout -b add_page_for_samvera_connect

3. Create a new file under pages/help_improve_this_site.md.

4. Add the content (see ticket).

5. Add the page to the menu.

6. Build site and run the jekyll built-in server.

   1. bundle exec jekyll build
   2. bundle exec jekyll serve

7. Submit PR and assign a reviewer.

8. Review, merge, and behold the content!

Working with styles (10 min)

Here we're going to increase the size and weight of the top nav menu items. This will illustrate how CSS works.

1. Find the ticket, assign someone, and move the ticket in the project board.

2. Create a branch for our work. git checkout -b top_nav_font

3. Find the CSS rules for the top nav menu items and increase the font size.

4. Start Jekyll server to see results.

5. Commit code, create PR, assign reviewer.

6. Review and merge.

Debugging: dump liquid variables to console as JSON objects (10 min)

1. Get the latest code.

2. Create _includes/dump.html.

3. Add code this code and save.

   <!--
   Dumps Liquid variables to a console as JSON objects.
    -->
   <script type="text/javascript">
     console.log("Dumping...");
     console.log({{ include.dump | jsonify }});
   </script>
   
   

4. From a layout or an include, you can now run:

   {% include dump.html dump=my_var %}
   

Plugins and Github Pages (15 min)

This is a discussion and a brief demonstration of using a plugin with a Jekyll site on Github Pages.

1. Briefly describe the flow of data from

   1. Starts in YAMLin _data dirctory or in Page/Post frontmatter.
   2. Processed by Ruby (including custom plugins)
   3. Assigned to Liquid variables.

2. Github Pages will not run custom plugins for security reasons.

3. Github Pages will run supported plugins.

4. Show browse pages page.

5. On local machine, open _plugins/browse_pages.rb.

6. Explain what it's doing

   1. Use pry to inspect data in the plugin.
   2. Use dump.html to inspect data in the template.

7. Explain the GithubPages "gotcha".

8. View and explain the purpose of GithubPagesHelper plugin.

Testing with RSpec and Capybara (10 min)

1. Get the latest code.

2. From project root, run

bundle exec rspec spec/homepage_spec.rb

1. It may fail because the site didn't have time to build.

• Open spec/homepage_spec.rb and notice it is trying to visit /.

1. Allow time to build the site with:

   WAIT_FOR_JEKYLL=5 bundle exec rspec spec/homepage_spec.rb
   

2. The rack-jekyll gem builds a Jekyll site as a Rack application that can be used with Capybara.

3. See spec/spec_helper.rb

• Secret sauce is Capybara.app = Rack::Jekyll.new(force_build: true)
• WAIT_FOR_JEKYLL env var is used to give the site time to build.

Up next for Samvera.github.io

1. Navigation refactor and content organization.
   • Separate menus into sections, based on audience.
   • Currently some work on refactoring menus.
2. Versions
   • Versions present a unique challenge for this site.
   • Current code could some refactoring to DRY things up and require less work from content contributors.
3. Consider separating source into different repository.
   • Makes using custom plugins easier.