/communicate-using-markdown

Creative Commons Attribution 4.0 InternationalCC-BY-4.0

Communicate using Markdown

Organize ideas and collaborate using Markdown, a lightweight language for text formatting.

Step 1: Add headers

Welcome to "Communicate using Markdown"! 👋

What is Markdown? Markdown is a lightweight syntax for communicating on GitHub. You can format text to add heading, lists, bold, italics, tables, and many other stylings. You can use Markdown most places around GitHub:

What is a header? A header is a larger bit of text at the beginning of a section. There are six sizes.

Example

# This is an <h1> header, which is the largest
## This is an <h2> header
###### This is an <h6> header, which is the smallest

How it looks

This is an <h1> header, which is the largest

This is an <h2> header

This is an <h6> header, which is the smallest

⌨️ Activity: Edit your file with headers

  1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
  2. Open the pull requests tab.
  3. Open the pull request we made for you.
  4. In this pull request, go to the Files changed tab.
  5. Select Edit file from the three dotted ... menu in the upper right corner of the file view on index.md.
  6. On the Edit file tab, add a #, followed by a space, before the content to make it an H1 Header. You can add more headers, using one to six # characters followed by a space.
  7. Above your new content, click Preview.
  8. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file.
  9. Click Commit changes.
  10. Wait about 20 seconds then refresh this page for the next step.

Step 2: Add an image

Great job adding headers to the file ✨

Let's add an image. Include descriptive text in the square brackets. This text is read aloud for people using screen readers. It's also shown at times when your image doesn't display, such as when there's a poor connection. You can see the syntax for images below:

Example

![Image of Yaktocat](https://octodex.github.com/images/yaktocat.png)

How it looks

Image of Yaktocat

⌨️ Activity: Adding an image

  1. As you did before, edit the index.md file in this pull request.
  2. In the file, add the correct Markdown for your image of choice. Don't forget to include alt-text!
  3. Use the Preview tab to check your Markdown formatting.
  4. Commit your changes.
  5. Wait about 20 seconds then refresh this page for the next step.

Step 3: Add a code example

Great job adding an image to the file 🎉

In addition to code blocks, some code blocks should be rendered differently depending on the language, such as JavaScript or command-line text.

Example

```
$ git init
Initialized empty Git repository in /Users/skills/Projects/recipe-repository/.git/
```

How it looks

$ git init
Initialized empty Git repository in /Users/skills/Projects/recipe-repository/.git/

⌨️ Activity: Adding a code example

  1. As you did before, edit the file in this pull request.
  2. In the file, add the correct Markdown for a code example of your choice.
  3. Use the Preview tab to check your Markdown formatting.
  4. Commit your changes.
  5. Wait about 20 seconds then refresh this page for the next step.

Step 4: Make a task list

Great job adding a code example to the file 🥳

What is a task list? A task list creates checkboxes to check off. They're very useful for tracking issues and pull requests. If you include a task list in the body of an issue or pull request, you'll see a progress indicator in your issue list. The syntax for task lists is very specific. Be sure to include the spaces where required, or else they won't render.

Example

- [x] List syntax is required
- [x] This item is complete
- [ ] This item is not complete

How it looks

  • List syntax is required
  • This item is complete
  • This item is not complete

⌨️ Activity: Add a task list

GitHub Actions went ahead and made a branch and a pull request for you. So you'll need to add to the file we've created in the branch, and we will check your work as you work through this course!

  1. Return to your pull request.

  2. Use Markdown to create a task list. Here is an example:

    - [ ] Turn on GitHub Pages
- [ ] Outline my portfolio
- [ ] Introduce myself to the world

    Remember, a task list starts with the syntax - [ ] and then the task list item. The formatting is specific!

  3. Use the Preview tab to check your Markdown formatting.

  4. Commit the changes to the file.

  5. Wait about 20 seconds then refresh this page for the next step.

Step 5: Merge your pull request

Great job adding a task list to the file ❤️

You can now merge your pull request!

⌨️ Activity: Merge your pull request

  1. Click Merge pull request.
  2. Wait about 20 seconds then refresh this page for the next step.

Finish

Congratulations friend, you've completed this course!

celebrate

Here's a recap of all the tasks you've accomplished in your repository:

  1. You learned about Markdown, headings, images, code examples, and task lists.
  2. You created and merged a Markdown file.
  3. You learned an essential GitHub skill. 🎉

What's next?

  • You can enable GitHub Pages and see your Markdown file as a website!
    1. Under your repository name at the upper right, click ⚙️ Settings.
    2. Then on the lower left, click Pages.
    3. In the GitHub Pages section, use the Source drop-down menu to select main as your GitHub Pages publishing source.
    4. Click the Save button.
    5. Wait about 30 seconds then refresh the page. When you see "Your site is published at ..." you can click on the link to see your published site.
  • Learn more about Markdown.
  • We'd love to hear what you thought of this course in our discussion board
  • Take another GitHub Skills course.
  • Read the GitHub Getting Started docs.
  • To find projects to contribute to, check out GitHub Explore.

Get help: Post in our discussion board • Review the GitHub status page

© 2022 GitHub • Code of Conduct • CC-BY-4.0 License