carpentries-incubator / jekyll-pages-novice

Building Websites with Jekyll & GitHub Pages.

Building Websites with Jekyll and GitHub Pages

This lesson teaches the basics of creating, configuring, and updating a static website with GitHub Pages and Jekyll. The lesson is aimed at researchers and research software engineers who understand what a variable is and are familiar with the GitHub web interface. Read more about the target audience and learning objectives on the lesson homepage.

Development Status

The lesson is currently in a beta state, meaning that it has been tested a few times at workshops and is ready to be taught by others. However, the lesson is not currently being developed nor is actively maintained.

Maintainer(s)

Past maintainers of this lesson are:

• Renato Alves
• Anne Fouilloux
• Toby Hodges
• Aleksandra Nenadic (Lead Maintainer)
• Sarah Stevens

Citation

See CITATION.cff for citation information, including a list of authors. (Read more about the Citation File Format and how to use it.)

Contact

Please get in touch with the original maintainers of the lesson with any questions.

jekyll-pages-novice's Issues

Files overview diagram

I was wondering if it would be good to have an overview of all the files that compose a website - perhaps at the end of the lesson as a recap.

I did not have the time to draw it but this image captures the idea:
https://razorsite.co/img/bowtie-theme-structure.jpg

List rendered from 1. instead of 23. in Episode 02 Exercise "Lists, enumerations"

Also, "4. without disturbing the enumeration count." sub-bullet point in the solution needs to be consistent with exercise body.

Exercise: static site generators

in 01-introduction.md

Need an exercise to test understanding of when it's appropriate to use an SSG/GitHub Pages

Write learner profiles

the lesson needs some learner profiles, to describe its target audience. These should go into a new file at files/audience.md.

Shorter headings in episode 03 needed

Need a second eye :-).

Instructions for local builds

We need an Extras page describing steps required to build and serve a site locally, for Windows (if possible?), MacOS, and Linux.

Remove outline from "Authoring with Markdown" episode

The outline is still at the top of this lesson

Use Title Case for Everything

We should be consistent on styling, and decided at the October lesson sprint to adopt Proper Title Casing for section/challenge/solution/callout/everything headings. At some stage, it would be great if someone could do a thorough sweep of all our lesson content to enforce consistency.

For all other style considerations, we defer to The Carpentries lesson style guide

Exercise(s): publish Markdown files as HTML on the web with GitHub Pages

in 03-github-pages.md

This one is probably multiple exercises, as it includes setting up GitHub Pages and editing/creating a Markdown file to be converted to HTML.

Review and reword (if needed) CONTRIBUTING.md

Fix capitalisation on learning objectives in all episodes.

I still think of learning objectives as finishing the sentence "After following this episode, learners will be able to..." which is why I have the habit of writing them with the first word starting in lowercase. But this doesn't fit with the lesson template and #60 has forced me to face up to the reality that they should start with an uppercase letter to remain consistent with the Questions and Key Points 😑 This needs to be fixed in all episodes.

Readme.md to index.md coordination?

In Review of #28, it came up that maybe we should have them learn Markdown by working in the README.md and then changing that to the index.md in the beginning of the github episode. Maybe something to discuss and coordinate at the next sprint?

plan material for GitHub Pages episode

We can use this Issue as a place for discussion around the GitHub Pages episode. Next steps might include:

• draft concept map for the episode
• review learning objective(s) & bullet point plan
• design exercise(s) to fit the episode learning objective(s)

Create an end-of-the-lesson episode

To include, for example:

• a short summary
• a curated diagram of a real life jekyll website (see #78)
• "where to go from here" pointers to further resources

update reference to previous epsiode in ep3 intro

Need to make sure Episode 3 says that the GitHub repository was set up at the end of episode 1.

Update AUTHORS

Everyone could just add their details?

Split up 05-starting-jekyll?

The Starting with Jekyll episode is probably going to be too long. What's the best point to split it? Perhaps put includes material into its own episode?

Expand README.md

"Lesson material" is not very descriptive! The README should be updated to include:

• more information about the lesson
• its high-level objectives
• a link to the HackMD & Slack channel
• the planned schedule for development and sprints

and anything else you think would be useful for potential contributors.

I'll take care of this soon (at the 6 October sprint at the latest) but, if anyone else wants to take on some/all of the above, please go ahead!

Exercise: themes

in 06-templates.md

need an exercise testing knowledge of finding/using pre-existing (remote?) themes. This is relevant to #11

Add optional page variable reference from other page

This issue came up in reviewing PR #27

@unode suggested the addition of an exercise to the starting jekyll episode where we try to refer to a {{ page.(...) }} variable that is defined in another document

Finish_02_markdown_challenges

Add challenge on links
Tobys suggestion

Plan material for Jekyll basics episode

We can use this Issue as a place for discussion around the Starting with Jekyll episode. Next steps might include:

• draft concept map for the episode
• review learning objective(s) & bullet point plan
• design exercise(s) to fit the episode learning objective(s)

Arrays & Collections episode

Here's my suggested outline for a final episode on arrays, loops, and collections:

• arrays in Jekyll: using the team_members example from #29, add an array variable to _config.yml and use a loop to list team members on a (new) team.md page
• use the where filter to pull out a team member with a particular job title. (Might need to combine this with another filter e.g. first - scrap this example if it gets too complicated...)
• with motivation to list blog posts automatically, configure a posts collection in config.yml and relocate the blog posts to appear in that collection. Add a new blog.md page to list posts sorted by publication_date.

Episode 02, exercise "Links" - code block in the exercise body is redundant

Not quite sure but feels like code block in the exercise body is redundant and should only be in the solution body.

Add early callout to forewarn of github changes making screenshots outdated

Thinking maybe we should mention that github is always changes so occasionally they may rearrange settings that asks folks to file an issue if they notice that settings are not where expected based on screenshots?

Notes reference

The notes for the sprints to work on these lessons can be found here.

When sprint is finished, maybe we should move some of the motivation and info to instructor notes?

Exercise: using page layouts

in 06-templates.md

need an exercise covering page layouts and _layouts

Finish callout 'Customising domain' in episode 03

Test the materials ahead of Pilot 1 by 9th November

People involved:

• Anne
• Julian
• Renato

Things to do:

• Review episodes from the beginning through the end of the Filters episode (do not worry about the last episode on Loops)
• File issues you discover along the way (think SMART!)
• Check you name off the above list once finished and make a comment on this issue

Sign up to test materials ahead of pilot 1 on 11-Nov

Sign your name here if you can test the materials:

• Anne
• Julian
• Renato

Teach collections, loops, etc?

Would it be a good idea to cover collections, for loops, conditionals, and other Liquid things?

Plan material for templates episode

We can use this Issue as a place for discussion around the Page Templates episode. Next steps might include:

• draft concept map for the episode
• review learning objective(s) & bullet point plan
• design exercise(s) to fit the episode learning objective(s)

Exercise: Jekyll variable substitution

in 05-starting-jekyll.md: need an exercise covering variable substitution in Jekyll.

Add the banner image to the example repository

Instead of loading the image from this repository, we should include the image in the example repository the learners are constructing as they work through the lesson. We can ask them to download it from this repo and upload it to theirs. Just need to add in some instructions for this at the start of the Includes episode...

Plan material for GitLab pages episode

We can use this Issue as a place for discussion around the GitLab Pages episode. Next steps might include:

• draft concept map for the episode
• review learning objective(s) & bullet point plan
• design exercise(s) to fit the episode learning objective(s)

Note: if focusing on GitHub Pages for now, all other episodes should take precedence over this one...

Draft_02_markdown

This is a dummy issue mimicking an empty Gitlab-merge-request and serving as a place to talk.

Improve Screenshot Sizes or Level of Perception

Some screenshots and the font sizes they contain are very large compared to the font of the text of the instructions outside the images.

Adjusting the size of the screenshots may help to increase readability and balance the level of perception of instruction and screenshot. Putting a frame / box around screenshots may be an alternative way of dealing with this.

Example

Exercise: `include`

in 05-starting-jekyll.md

need an exercise to test knowledge of _includes and {% include ... %}

Change episode numbers

At the moment we are missing episode 04 - so once we settle on episodes we should change the numbers to reflect this.

Finish exercise 01 in episode 03

Adding content (section About) to index.md file.

Update Setup page

Include making github account and anything else we can think of.

Exercise: adjusting site config

in 05-starting-jekyll.md:

need an exercise to test understanding of how site config works from, _config.yml. This exercise (or another, separate one) should also include working with global variables (i.e. site.variable_name where variable_name was set in _config.yml).

Exercise: layout inheritance

in 06-templates.md

need an episode on creating new layouts based on old layouts

Writing basic HTML TODO

A callout in the introduction with a TODO:

>>> Writing Basic HTML
TODO: brief overview of tags, including strong, heading, and link.
Fill-in-the-blanks exercise to write HTML to recreate some example text.

07-filters needs learning objectives etc

07-filters.md front matter needs some:

• questions
• learning objectives
• key points

Plan material for Filters episode

We can use this Issue as a place for discussion around the Working with Filters episode. Next steps might include:

• draft concept map for the episode
• write learning objective(s)
• review bullet point plan
• design exercise(s) to fit the episode learning objective(s)

Add Markdown/code for the lesson in example website

As we build the website, we should make sure the Markdown/code works as expected and that we end up with an end product (reference project website). @sstevens2 has created a repo for this purpose: https://github.com/sstevens2/group-website
I needs filling in.

Finish exercise 02 in episode 03

Adding links between pages.

Mention order of steps in Jekyll rendering process

In Layouts episode, mention https://jekyllrb.com/docs/rendering-process/ as something to watch out for. This is particularly relevant as a follow-up to the callout about linkrefs in the Includes episode, to explain why we can't write `{% include links.md %} into the page layout file.

Include an episode on themes?

It might be a good idea to dedicate a whole episode to themes and remote themes for Jekyll sites?