jekyll-pages-novice

# jekyll-pages-novice Jekyll GitHub pages lesson development team's rolling meeting notes. The original team members: Toby Hodges, Sarah Stevens, Anne Fouilloux, Renato Alves, Julian Bauer, Aleksandra Nenadic ## Links - [Lesson GitHub Repository][lesson-github] - [Lesson pages][lesson-pages] - [Slack channel](https://swcarpentry.slack.com/archives/C0186GK56UC) - you need to [be a member of The Carpentries Slack](https://swc-slack-invite.herokuapp.com/) first ## Style Notes - Use Title Case Everywhere! - For everything else, refer to The Carpentries style guide: https://carpentries.github.io/lesson-example/06-style-guide/index.html ## Timeline 2021 - 12 Jan: Check-in, Planning, and Lesson Development - 2 Feb: Lesson Development Sprint - 2 Mar: Lesson Development Sprint - 6 Apr: Lesson Development Sprint - 11 May: Lesson Development Sprint - 21 June: Lesson Polishing ## Lesson Run-through 2021-06-21 Attending: - Aleks Nenadic - Toby Hodges - Sarah Stevens Tasks: - Go through together: Making consistent Screenshots (#107) DONE - Go through together: Check that all images have alt text DONE - Go through together: Making consistent the we/I langauge (#245) DONE - Go through together: Check all exercises and sections are using Title Case DONE ## Meeting/Sprint 2021-05-11 - What we are working on: - Toby: - ~~[#222](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/222)~~ ~~[PR Submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/238)~~ Merged - ~~[#212](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/212)~~ Already fixed - Aleks: - [#208](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/208) - ~~[PR Submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/242)~~ Merged - [#209](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/209) - reassigned to Anne - ~~[#210](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/210) - [PR submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/248) & merged~~ - [#213](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/213) - ~~[PR submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/243)~~ Merged - Sarah: - ~~[#230](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/230) PR Submitted~~ Merged - ~~[#122](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/122)~~ ~~PR Submitted~~ Merged - Working on exercies to add to wrap-up to have them try a template - [Drafting PR](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/237) - ~~[#235](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/235)~~ [PR Submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/240) - Renato: - ~~[#197](https://github.com/carpentries-incubator/jekyll-pages-novice/issues/197)~~ ~~[PR Submitted](https://github.com/carpentries-incubator/jekyll-pages-novice/pull/242)~~ Merged - for whoever gets to it first: ## Meeting/Sprint 2021-03-02 - Attending: Renato, Sarah, Toby, maybe Aleks later on - Question from Aleks: who will teach each section next week? - Sarah on Day 1, Renato on Day 2, Renato on Day 3 but he would really like some help - Aleks? Toby? - Question from Aleks: are we ok with the schedule? Workshop website: https://anenadic.github.io/2021-03-09-jekyll/ - Sarah agreed that we can get through episodes 1-4 on day 1, so we should adjust the schedule to put Starting with Jekyll on day 1 - What do we need to do to close https://github.com/carpentries-incubator/jekyll-pages-novice/issues/127? - this issue is about motivating examples, and the need or otherwise for learners to have built something beautiful by the end of the lesson. As I see it, we have three options: 1. leave the lesson "as-is", building a kinda ugly website during the lesson that nevertheless guides learners through the key features of Jekyll. Bookend the lesson with a look at the lesson repository at the start and end, as a "this is the kind of thing you can really do with this stuff" example 2. add in some additional content about styling e.g. using Bootstrap to do some basic styling of the layouts we build in the lesson 3. switch to using one of GitHub's built-in themes/start from an imported theme. This last option makes the prettiest website, but also makes the teaching much harder and requires a fairly major re-organisation of our lesson! - we will add a question about this to the post-workshop survey to use next week. ### Sprinting - Toby: update Aleks' workshop website :white_check_mark: - address some issues - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/189 - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/187 - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/122 - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/37 - Sarah: start working through the lesson as prep for the pilot next week - Renato: start working through the lesson as prep for the pilot next week ## Meeting/Sprint 2021-02-02 - Attending: Renato, Aleks, Anne, Toby - Facilitator: Aleks (but ended up being Toby as Aleks realised too late she was meant to do it :-) [name=toby]: this was my fault for taking over the meeting. Sorry everyone! - Notetaker: Aleks **3rd Jekyll pilot workshop 9-11 March:** - Workshop website: https://anenadic.github.io/2021-03-09-jekyll/ - [Instructor/Helper CodiMD](https://codimd.carpentries.org/RIvuDoIpRa62F5FUpnC3Tw?edit) - [Learner CodiMD](https://codimd.carpentries.org/2021-03-09-jekyll?edit) - Tuesday 9th March: Sarah to teach, Anne to help, Aleks to facilitate/help - Wednesday 10th March: Renato to teach Toby, Sarah, Aleks to help - Thursday 11th March: Renato to teach Toby, Sarah, Aleks to help - **Action: Aleks to send calendar invitation** - Done - **Action: Toby to create pre-worshop survey** to gauge people's familiarity with the material so we can speed things up/adjust the pace accordingly - Aleks will share example of SSI surveys sometimes used for Carpentries workshops that they host (Done in the Zoom chat - get in touch with Aleks if you need the link to be resent). Plan for today/3rd pilot/beta: - Check 'Project 2' issues for beta release: https://github.com/carpentries-incubator/jekyll-pages-novice/projects/2 - Toby: missing array and collections - leks: missing wrap-up episode - layouts now pulled into the repository (so the two examples in the episode can be merged) and Renato added bits under Extras - Renato: support for GitLab in this lesson - another sprint in March that can be used - Anne: some issues assigned to her are obsolete - need team discussion then close issues that are alerady taken care of - Sarah: remake all screenshots issue or demonstrate how things can go wrong issue (the latter ended up being chosen and the remaking screenshots left for the March sprint or for someone from the community to pick it up as it is labelled as 'help-wanted') - Extra pages - e.g. about CodiMD/HedgeDoc, GitPod - what to do about them, there is loads of useful things and tools we learned and used - Put them in the extras - Renato: We might need to ask carpentries to set CMD_DEFAULT_USE_HARD_BREAK to true for compatible behavior from codimd. - Recommendations to use CodiMD for taking notes, link to CodeRefinery's CodiMD page if it si well-maintained - Setup instructions for local Jekyll installs https://carpentries.github.io/lesson-example/setup.html - a bit specific to the lesson template, so not exactly what we want - Instead or in addition to GitPod we may wanto to mention https://github.com/features/codespaces ## Meeting/Sprint 2021-01-12 **_starting 30 mins late_** - Attending: Renato, Sarah, Aleks, Toby, Anne - Facilitator: Toby - Issue Reporter: - Note Taker: ### Agenda - planning the development timeline for 2021 - any plans for more pilot workshops? - these two things are tied together. teach whole lesson over two half-days? Aleks volunteers to organise/host that (in UTC). perhaps 09:30-13:00? or over two afternoons to include Sarah? - homeschooling is happening again in many countries - four two-hour sessions? or three 3-hour sessions 13:00-16:00 UTC - having 3 3-hour sessions gives us an opportunity to allow people to skip the first session with intro, HTML and MArkdown if they are already familiar with this - who would teach? - Sarah (depending on date) - Renato - Anne - Toby (but will defer to anyone else) - mid-March or early April? - **9,10,11 March** - **Action: Aleks to make a website/registration/schedule and share with the team** - **Aim to do a beta release just after the sprint on 6th April** - blog post & discussion session ([Slack thread for reference](https://swcarpentry.slack.com/archives/C0186GK56UC/p1607074882015400)) - if possible, please review [blog post draft](https://codimd.carpentries.org/uK4KDdR-SsKfWhDC_pmRnA?both) before the end of this week - 15:00 UTC 1 February - themed community discussion? - 15:00 UK time; 16:00 Central Europe; 08:00 Wisconsin - when should we target beta release? - 30 April 2021 - current state of the Jekyll lesson - issue triage: - assign all unassigned issues - re-assign issues assigned to Julian - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/147 - https://github.com/carpentries-incubator/jekyll-pages-novice/issues/122 - lesson development: - what are you going to work on today? - Toby: I will start with https://github.com/carpentries-incubator/jekyll-pages-novice/issues/168 - shared timer: https://cuckoo.team/jekyll-lesson-sprint ## UW-Madison Workshops Workshops capped at 20 people (9 and 5 registered so far for each workshop, respectively). Registration closes the Friday before each instance. Sarah will host, provide introduction, will also provide pre- & post-workshop survey results, virtual stickies -> Sarah has posted the Google Drive link in Slack [2020-11-11 15:00 UTC](https://www.timeanddate.com/worldclock/fixedtime.html?msg=Jekyll+Pages+Mini-Workshop&iso=20201111T09&p1=142&ah=3&am=30) Instructors + Toby Hodges + Anne Fouilloux Helpers + Toby Hodges + Sarah Stevens + John Caskey + Scott Prater [2020-11-25 15:00 UTC](https://www.timeanddate.com/worldclock/fixedtime.html?msg=Jekyll+Pages+Mini-Workshop&iso=20201125T09&p1=142&ah=3&am=30) Instructors + Toby Hodges + Aleks Nenadic Helpers + Toby Hodges + Sarah Stevens + Julian Bauer + Aleks Nenadic + John Caskey + Trisha Adamus + Renato Alves ## Sprint 2020-12-01 Attending: Toby, Julian, Sarah, Aleks Agenda: - Issue go-through post 2nd pilot (Toby as Issue Reporter) - doing it as a group - Issue fixing Discussions ## Sprint 2020-11-23 To prioritise today: - pare down the Markdown episode - add a demo at the end of the lesson? - a short walkthrough of what you can do with this stuff once you've learned it, to be covered at the end of every workshop _regardless_ of how far through the lesson material you have got before that point. - Toby & Aleks to plan their teaching on the mini-workshop on Wednesday ### Markdown - Anne - Julian - Sarah ### Demo - Renato - Toby ## Sprint 2020-11-03 Last sprint before the first pilot! Let's make it count! Agenda - Rotating roles intro (Toby) - Facilitator: Toby (for first discussion) - Issue Reporter: Aleks (for first discussion) - Time Keeper: Sarah (for first discussion) - <https://cuckoo.team/jekyll-lesson-sprint> - Note Taker (optional/everyone) - Update from the Issue Reporter (this time it is Aleks) - (10-15 min) - Prep for the first pilot: - (15-20 min) - Volunteers to try working through the lesson before 11-Nov? - What needs finishing off? See here: https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/projects/1 - What are you working on today? - Aleks: tidying up the issues and PRs in our GH repo (in my current role as the Issue Reporter) and working on the issues assigned to me for this sprint - Toby: https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/issues/79 - Julia: work on issues assigned to me - Anne: deal with exercise duplication issue - Renato: get reoriented with the project before I pick an issue Update from this sprint's Issue Reporter (Aleks) - Should have really done this sooner - but it is never too late to employ good software engineering practices and practice what we preach :-) - All issues need to be reported (by the Issue Reporter or other members of the team). - Make sure to include a good description of the issue, a screenshot if available, etc. Issue Reporter can help with this too. - All issues need to be triaged: i.e. to have at least one person assigned (if you are assigned but do not think you are suitable/cannot do it - feel free to reassign). - Make issues "SMART" - e.g. specific and achievable; avoid open-ended issues. Split in several issues if need be, or use checkboxes for sub-issues. For example, "write episode 05" is too wide and not specific enough but sometimes necessary to get us started. As we add more content issues will naturally become more focussed. - All PRs need to have reviewers assigned. - Check issues assigned to you at the start of the sprint and decide what are you going to work on. - Tidy up! Delete unused/merged branches. Issue Reporter can help with this too. - All of the above things can be done by Issue Reporter but it would be helpful if people could stick to the above guidelines too :-) :heart_decoration: #### Check-ins 14:30 UTC - Facilitator: Aleks - Issue Reporter: Sarah - Time Keeper: Julian - Note Taker (optional/everyone) 15:45 UTC - Facilitator: Sarah - Issue Reporter: Julian - Time Keeper: Anne - Note Taker (optional/everyone) ## Sprint 2020-10-06 Issues for discussion: - conventions for YAML front matter: - quotes around string values? if so, single or double? - running example throughout lesson - assigning instructors+helpers for November - things we need to agree: - name of repository we're creating - `group-website`? +1 - add setup of repository to episode 1 - answer question about "why GitHub Pages?" in episode 1 - where does "starting with Jekyll" start? - proposal to move content from "Website Configuration" down, into episode 4 - waiting to discuss with Aleks - should we add an epsiode about collections? would allow us to include a bit about blogposts, which is probably what a lot of people want to learn. **If you'd like your PRs to count towards Hacktoberfest and a free T-shirt or planting a tree, register at https://hacktoberfest.digitalocean.com/** Tasks for today: * update README - Toby (https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/issues/41) * adjust exercises on episode 2 to construct README for beginning of ep. 3 - Julian * add setup of repository to episode 1 - Sarah * answer question about "why GitHub Pages?" in episode 1 - Toby ## Sprint 2020-09-01 Issues for discussion: https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/issues/22 https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/issues/18 https://github.com/carpentries-incubator/building-websites-with-jekyll-and-github-or-gitlab/issues/11 ### Attending: Toby Hodges, Sarah Stevens, Anne Foullioux, Renato Alves, Julian Bauer, Aleksandra Nenadic ### Notes #### Higher-level narrative - As agreed in the previous meeting, we agreed to focus (for now) on working only from GitHub and all exercises will be designed like this. - The higher level narrative is starting from a blank repository and showing learners step by step all the magic that happens when creating a website and that it can be as simple as having an index page and turning gh-pages on. Once learners are comfortable with Markdown, layout, config file and including content from other files/partials - we can then proceed to an episode to show them how to build a website from a template (when they have gained an understanding of all the wiring behind) - this can be a different repository and it is still to be decided what kind of template we will use (e.g. everyone can build their own website) and this can be an opportunity to show learners how to host multiple website under GitHub IO (and perhaps building their main/personal website in IO root). #### Episodes 1 - Introduction 2 - Markdown - Julian 3 - GitHub Pages - Aleks & Anne 4 - ~~GitLab Pages~~ 5 - Jekyll intro - Sarah / Anne / Renato 6 - Page templates/**layouts** 7 - Includes 8 - Website templates/**themes** 9 - Filters #### Learner Profiles - Person who knows Git already - Create a research project/lab/group website to e.g. put info, store documentation and track issues, that can be worked on collaboratively within a team - Create a personal website or a publicly visible CV page - Carpentries instructor to create workshop websites, not much or no Git - Developer who wants to create documentation pages for their software/project - Someone looking for a free web hosting platform, little or limited HTML/CSS knowledge Actions: - [x] Toby to change episode numbers to add Includes episode - [x] Toby (or anyone) to put the Gitlab episode under Extras (or an alternative to GitHub in the end e.g. in a summary episode) - [name=toby] it's in `_extras` for now - [ ] Toby to set up Projects board on lesson GitHub repo, organise issues by episode, etc - [x] Renato to explore having solutions as working examples in a subfolder of the same repository - [name=Renato] - Mostly works with the caveat that we can only have one `_config.yml` per repository and this affects all exercises. See [the repository structure](https://github.com/unode/jekyll-sandbox) and [the rendered pages](https://unode.github.io/jekyll-sandbox/) Extras: - Building all this locally - Using GitLab instead of GitHub ## Meeting 2020-07-30 ### Attending: Toby Hodges, Sarah Stevens, Anne Foullioux, Renato Alves, Julian Bauer, Aleksandra Nenadic ### Notes - Incubator - focus on GitHub for now - editor/environment - write a separate "building locally" episode, but try to make all other episodes compatible with working in GitHub i.e. without need for prior knowledge of CLI Git - flavour - stick with GitHub for now, add to Julian's callout box if necessary - timeframe? - see plan at top of document - contact? Slack channel? - done - [click here](https://swcarpentry.slack.com/archives/C0186GK56UC) to join - Can steal from [this repo](https://combee-uw-madison.github.io/2019-03-20-GHpages-workshop/) - Plan for sprint - Sept 1st at 7am in Madison, WI - 4 hours? - All there at beginning but then can be flexible to availiblty later - Check in as a group before anyone has to leave - First Tuesday of each month, same time, until Dec. - Oct 6th, Nov 3rd, Dec 1st ### Action Items: - [x] Toby: Request to move [this repo](https://tobyhodges.github.io/building-websites-with-jekyll-and-github-or-gitlab/) into [the Carpentries Incubator](https://github.com/carpentries-incubator/proposals/issues) - [x] Toby: create granular issues e.g. "create challenge on [concept]", "write learner profiles" - [x] Sarah: Calendar invites to sprints (w/Zoom) ## Concept map (WIP) [Stuff you can do with Mermaid](https://mermaid-js.github.io/mermaid/#/flowchart) ```mermaid graph TD %% Section for names of nodes Br("Browser") HTML("HTML") CSS("CSS") SG("Static generator") GH("GitHub") MD("Markdown") MD-H("Header") MD-B("Bold") MD-E("Emphasis") MD-L("List") MD-LU("Ordered") MD-LO("Unordered") YAML("YAML") JK("Jekyll") JKP("Page") JKS("Site") FM("Front Matter") V("Variables") IN("Includes") TPL("Templates") LAY("Layouts") TH("Themes") %% Section for connections between nodes Br --> HTML & CSS HTML & CSS <--> SG SG --> JK JKS --> V JKP --> V JKS --> TPL TPL --> IN TPL --> LAY TPL --> TH JKP --> FM JK --> JKS YAML --> JKS JKS --> JKP JKS --> TH JK --> MD SG --> GH MD --> MD-H MD --> MD-B MD --> MD-E MD --> MD-L MD-L --> MD-LU MD-L --> MD-LO ```  [lesson-github]: https://github.com/carpentries-incubator/jekyll-pages-novice [lesson-pages]: https://carpentries-incubator.github.io/jekyll-pages-novice

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.