Lesson 3: Introduction to Markdown

How can I utilize Markdown in project documentation?

Overview

This course is language agnostic, so to find common ground in the curriculum we will be utilizing Markdown in Unit 0. Markdown is useful in that it will also allow students to easily format their project documentation in their readme pages and may prove useful later in their careers!

In this lesson, students will explore the basics of Markdown through a series of tutorials. Please note that Markdown, similar to HTML, is hard to break or have things go wrong - if they're typed incorrectly, the formatting simply won't show as intended.

Objectives

Students will be able to:

• Understand the basics of Markdown and its common use cases.

• Learn and practice basic Markdown formatting.

• Apply Markdown skills through hands-on tutorials and projects.

Suggested Duration

~2 class periods, 45 minutes each

NYS Computing Standards

• 9-12.DL.4 Independently select advanced digital tools and resources to create, revise, and publish complex digital artifacts or collection of artifacts

• 9-12.DL.5 Transfer knowledge of technology in order to use new and emerging technologies on multiple platforms.

Vocabulary

• Markdown: A lightweight markup language with plain text formatting syntax designed to be easy to read and write. It is often used to format readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.

• Markup Language: A system for annotating a document in a way that is syntactically distinguishable from the text. Examples include HTML, XML, and Markdown.

• Syntax: The set of rules that defines the combinations of symbols that are considered to be correctly structured documents or fragments in that language.

  • Common syntax students will utilize in Markdown will be headings, bold, italics, block quotes, lists, links, images, horizontal rules, codeblocks, and inline code.

• Plain Text: Text that contains no formatting, such as bold, italics, or links. Plain text is the opposite of rich text, which can include formatting.

• Formatting: The way in which text is arranged and styled, such as bold, italic, headings, lists, etc.

• Readme File: A text file containing information about other files in a directory or archive. Readme files are often written in Markdown.

Assessments

Formative:

• Tutorial completion

• Partner Profile

Summative:

• Upcoming end of unit project

Resources

• Learn Github Introduction: Module 2 (Codecademy)

• 10 Minute Markdown Tutorial (Commonmark.org)

• Interactive Markdown Tutorial (Longer Version)

• Learn Markdown in 30 Minutes (Youtube Tutorial)

• The Markdown Guide (Text Resource, PDF)

Do Now (~3-5 min)

Ask students to look at or reflect on different visuals around them (e.g., posters, websites, social media) and think about how these visuals avoid being a wall of text.

Students should record their thoughts using whatever notetaking practice/format you prefer in your classroom.

Mini Lesson: Introducing Markdown (~7 - 10 minutes)

After the Do Now, allow time for students to share and discuss their responses. Highlight key points such as the use of headings, lists, bold or italic text, and images to enhance readability.

From there, introduce students to the idea of markdown - explain places they may have already seen it (Reddit, using ** around words to make them bold, Github, some blogging platforms etc) Explain that Markdown is a lightweight markup language used to format text.

Show examples of Markdown formatting in contexts students might be familiar with:

• Bold text: **bold**

• Italic text: *italic*

• Headings: # Heading 1, ## Heading 2

• Lists: - item 1, 1. item 1

• Links: [title](http://...)

• Images: ![alt text](image.jpg)

You're encouraged to open up a github repo (look back to Lesson 1!) that has a robust README file as these are often written in markdown. If you view the file itself and the raw code, you will be able to see the markdown code alongside to text. Clicking between this and the output can be beneficial to student understanding - connections between HTML/websites can also be helpful.

Explain that learning Markdown is useful for creating well-formatted text without using a complex word processor. Emphasize that Markdown is easy to learn and will be a valuable skill for various applications, including creating documentation, blogging, and collaborating on GitHub.

Independent Work: Codecademy

Direct students to complete the second module on Markdown in the GitHub Codecademy course. Their progress from Lesson 1 should be saved in their accounts.

As with all of these tutorials, we are utilizing Codecademy for its safe sandbox environment; students may not finish everything, but should progress as far as possible.

Independent Work: Markdown Tutorial

Have students complete an additional Markdown tutorial for extra practice. Suggested tutorials could include:

• Markdown Tutorial (longer, if students need signficiantly more practice)

• CommonMark (10 minutes, recommended)

Partner Project: Make a Profile

This is likely the start of Day 2; if students are in need of a Do Now, consider a reflection question or code reading question based on what they learned the previous day.

Today, students will be primarily working on using the skills they learned in tutorial mode by interviewing a partner and creating a profile page (in Markdown) for them.

Frame the project in the context of creating a social media profile, such as those found on LinkedIn or Facebook.

Instructions:

• Pair up students and have them interview each other, gathering information such as:

  • Name

  • Interests

  • Hobbies

  • Favorite books/movies

  • A fun fact

  • Anything else you may want to include - think about your school/students when making prompts!

Creating the Profile:

• In their IDE of choice, have students make a new project directory.

• In that directory, they should touch partnerProfile.md to make a new Markdwon file to work in.

• Students will use Markdown to format the profile, incorporating elements like headings, lists, bold and italic text, and images (if available).

Suggestions:

• Provide a template or example profile to guide students.

• Offer support as students work on their profiles, ensuring they use Markdown correctly.

Wrap Up (~3 - 5 minutes)

If time permits, ask students to share out their student profiles - try to get at least 2-3 displayed on the screen.

As an exit slip, consider having students answer one or more of the following questions:

• What did you find most interesting about using Markdown?

• How do you think you might use Markdown in the future?

• What was the most challenging part of learning Markdown today?

Extensions

There is a lot to Markdown; we will not be covering it all, but for students racing ahead, encourage them to read the documentaiton to try and find the most interesting things they can possibly do with Markdown.