Markdown and Code
Learning Objectives:
In this section, students will:
- Learn what markdown is.
- Learn the basics of how to use markdown.
- Try using markdown.
Markdown and Code
As discussed in the previous section Links to an external site., files added to the local folder or directory are monitored by the GitHub Desktop application. These new files can be uploaded to GitHub by pushing commits that also describe what was changed and how those changes fit into the larger project.
When you created the new repository, there was already a file there. This was the READMEfile.
README
When looking at a repository on GitHub, the text shown to other users comes from its README file. This is part of every project and should explain what the other files are and include additional information on how to use them.
Many README files also have information on the project, its goals, and how it could be used with other tools and projects. As the first source of information, the README should, ideally, explain everything a user needs to know.
Markdown
The README (and other files) are written in a language called markdown. This is named as something of a joke. While others like HTML “mark-up” text, this language “marks-down” the text.
Markdown supports many of the same ideas of languages like HTML. It has multiple levels of headings.
It supports giving text emphasis and making it bold as well.
Ordered and unordered lists are also supported. Unlike HTML and CSS, however, spacing becomes important for sub-items. They should start at least two spaces in or at least a standard tabbed distance to indicate they are sub-items of another, higher-level item.
Adding Code
Open the README file with Atom Links to an external site. or another editor that understands markdown. (If the editor understands markdown, its color-coding will help when writing code and in understanding how it is applying different styles to text.)
Adding new markdown code will be shown in the editor (if it understands markdown) in a different color. Save the file after adding new markdown.
Opening the GitHub Desktop application will show those new changes to the file. Before the changes can be added to the GitHub repo, it needs a summary, description, and to be committed.
As reviewed in the previous section, clicking on “Push origin” after creating a new commit will send the changes to the GitHub repo.
Changes to the README file, once pushed to the public repo, will appear on the project page.
Making Small Changes to README and Other Files
While most changes should happen through something like the GitHub Desktop or another application, many (but not all) files can be changed through the “Edit this file” functionality when viewing the individual file on GitHub.
Because GitHub understands markdown, editing files written in the language allows for seeing a preview of those changes.
Changes can be made and then previewed before, like all other updates, writing a summary and description of the changes in a commit and submitting it to the repo.
Try it Yourself:
1) Use Markdown to change your README file to have two H1 headings.
2) Add at least two H2 headings.
3) Commit these changes