MarkDown

[lakruzz]

MarkDown is and absolutely adorable notation

Adorable because it's so elegant and simple that if it even qualifies as a language it's probably the easiest language in the world to learn.

It's my #️⃣1️⃣ goto-language when I facilitate learning in all the stuff that surrounds programming: git commits, -merging, -branching, documentation, issue tracking.

This is the crash course "Hello GitHub" I used it with the ITA students. It's an upgrade from the version I used with the DAT students. In both cases I had created a group exercise in GitHub Classroom, meaning that they would all work in the same repo.

👉 You can test-run the assignment yourself simply by creating your own repo off the template "Hello GitHub".

I have deliberately not given them any information on MarkDown other than the spoiler in the bottom of the README.md - I've copied it in here too:

Spoiler!

---

All you need to learn about (GitHub flavoured) MarkDown is hinted to you in the webpage.

All the time you spend on practicing and learning MarkDown is never wasted. You will be using it for the rest of your career as a developer!

---

This is also an introduction to the concept of figuring it out. I told them, that if they want my attention the can always create an issue and either mention or assign me in the issue. They figured it out.

When they are done (45 mins) some of them have come quite far and are capable of some advanced stuff like insert, size and align images. And some of them picked up themselves how to make permalinks to code snippest.

Here's an example of both:

A direct link to highlight lines #5-7 in the README.md. in the kea-dev/github-for-instructors repo. It appears that html "tricks" also works in MarkDown too, so something as simple as this this:

<img width="100" align="left" alt="image" src="https:/...">

Can create a small insert picture with wrapped around text like this:

At this point the assignment has made them create both a personal my-handle.md file in the repo and an issue each - both items support MarkDown so as we continue to explore together in class - they have the perfect test setup established already - they are all using the integrated online editor on GitHub. No setup or IDE needed.

I also show them that each issue has an open or next comment field (scroll to the bottom of this page) - so I encourage them to actually use comments on GitHub Issues as their note-taking technique.

We recap how to take screen captures directly to the clipboard (SHIFT+CTRL+CMD+4 on Mac WIN+SHIFT+S on windows), and paste them directly into the issue or .md file.

This way their comments are always in context of what they are working with, they are building up both a learning-trace and a personal portfolio - since the repo is theirs - forever.

👉 you should do the same 👈

By example of a line-highlight link - like the lines #5-7 in the README.md used above - I show them the exploding three-dot menu next to the highlighted code:

And we investigate some of these features too. Especially the "View File in GitHub.dev" option makes them generate variations of "wow!" sounds when they realize that it's not only a viewer, but actually and online VS Code editor.

One student found this video on YouTube and could school us all - me included - that when you are browsing files on GitHub, all you have to do is to hover over the file name - and while over it - hit the "." (dot) character!

As we explore, some are genuinely impressed - I hear the first "May we write our report in a .md file in the repository?" - it melts my heart! _"They get it!". And others don't get it

I ask them to bookmark the manual page: Writing on GitHubcontinue to show tricks and they try them out instantly in their .md files or issues. I go over stuff like automatically-expandable-mentions-and-keywords and the expandable/collapsable sections like the Spoiler text I showed previously.

Again, it's merely html helping out and in MarkDown the rule is, that any valid html is also valid MarkDown. So the details-summary notation works out-of-the-box - because it's valid html.

<details><summary>Spoiler!</summary>

---
All you need to learn about (GitHub flavoured) MarkDown is hinted to you in the webpage. 

<img 
  width="782" 
  alt="image" 
  src="https://user-images.githubusercontent.com/155492/215319730-3df5119d-2ec0-4b37-8faf-6686d43eaff9.png">

_All_ the time you spend on practicing and learning MarkDown is _never_ wasted. You will be using it for the rest of your career as a developer!

---

And then it turns out that it's not true - not in GitHub issues or .md files on GitHub at least 🤔 - I show the example:

A link like this <a href="." target="_blank" >text</a> doesn't work - it doesn't open the current page in a new browser tab - as expected.

We talk about GitHub Flavored MarkDown (GFM).

A google search on "github flavored markdown open link in new tab" reveals the Stack overflow post _open link in new tab with github markdown using target="blank"

The article explains quite simple both "Live with it - hold CTRL/CMD down when you click a link!" and also that it actually works in other implementations of MarkDown, such as KramDown.

"....other implementations????" I see smoke coming out of some of the students ears - it gives an opportunity to talk about the fact, that MarkDown is a notation - and while it's supported by many different tools they may have different implementations. Like GFM.

I mention JAM stacks (= JavaScript - API - MarkDown) as the nowadays standard for static web sites - I touch briefly on Hugo, Gatsby, Next.js and Jekyll - I use the docs.kea.dev as an example of a Jekyll implementation.

I show them the source repo - which is open source and explain the concept of GitHub Pages, how GitHub pages is not exclusively using Jekyll, but definitely tightly coupled to Jekyll. We go through some of the GitHub pages option in the settings of the repo.

I show them how a static website hosted by GitHub pages - such as docs.kea.dev/technology-intro i also written in MarkDown and that actually allows it - link to proof.

I show them how I set up the website as a Build in public site, so they can just have a look at the four closed issues on the repo and follow the commits attached to each issue:

Like

• Setup a site using github pages and Jekyll
• Use an external customisable jekyll theme kea-dev.github.io#2

An how each issue references a specific commit - 208f25e and 266e690 respectively - and how studying these commits tells a story - or leave trace, of what actually happened.

I show them how MarkDown is even applicable in the annotated comments to a commit.

MarkDown is essentially the essence of GitHub and I once again stress:

All the time you spend on practicing and learning MarkDown is never wasted. You will be using it for the rest of your career as a developer!

...At this point I'm not so worried if I lost some of them: Some get it, and I see that they are capable of helping each other out, but most importantly I'm not worried because I plan to repeat most of these points a 1000 times over and I plan to have them ask me for guidance, through the issues and annotated comments in their GitHub repos. They will pick up eventually.

Time to move on

Leave this issue (maybe even Close it!) and move on to the next one in your repo.