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.
- Go to https://github.com/samvera/samvera.github.io
- Clone the repo.
cd samvera.github.io
git pull
Here we'll create a new page called "Help Improve This Site".
-
Find the ticket, assign someone (a participant), and move the ticket in the project board.
-
Create branch
git checkout -b add_page_for_samvera_connect
-
Create a new file under
pages/help_improve_this_site.md
. -
Add the content (see ticket).
-
Add the page to the menu.
-
Build site and run the jekyll built-in server.
bundle exec jekyll build
bundle exec jekyll serve
-
Submit PR and assign a reviewer.
-
Review, merge, and behold the content!
Here we're going to increase the size and weight of the top nav menu items. This will illustrate how CSS works.
-
Find the ticket, assign someone, and move the ticket in the project board.
-
Create a branch for our work.
git checkout -b top_nav_font
-
Find the CSS rules for the top nav menu items and increase the font size.
-
Start Jekyll server to see results.
-
Commit code, create PR, assign reviewer.
-
Review and merge.
-
Get the latest code.
-
Create
_includes/dump.html
. -
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>
-
From a layout or an include, you can now run:
{% include dump.html dump=my_var %}
This is a discussion and a brief demonstration of using a plugin with a Jekyll site on Github Pages.
-
Briefly describe the flow of data from
- Starts in YAMLin
_data
dirctory or in Page/Post frontmatter. - Processed by Ruby (including custom plugins)
- Assigned to Liquid variables.
- Starts in YAMLin
-
Github Pages will not run custom plugins for security reasons.
-
Github Pages will run supported plugins.
-
Show browse pages page.
-
On local machine, open
_plugins/browse_pages.rb
. -
Explain what it's doing
- Use
pry
to inspect data in the plugin. - Use
dump.html
to inspect data in the template.
- Use
-
Explain the GithubPages "gotcha".
-
View and explain the purpose of
GithubPagesHelper
plugin.
-
Get the latest code.
-
From project root, run
bundle exec rspec spec/homepage_spec.rb
- It may fail because the site didn't have time to build.
- Open
spec/homepage_spec.rb
and notice it is trying to visit/
.
-
Allow time to build the site with:
WAIT_FOR_JEKYLL=5 bundle exec rspec spec/homepage_spec.rb
-
The
rack-jekyll
gem builds a Jekyll site as a Rack application that can be used with Capybara. -
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.
- Navigation refactor and content organization.
- Separate menus into sections, based on audience.
- Currently some work on refactoring menus.
- 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.
- Consider separating source into different repository.
- Makes using custom plugins easier.