Learning Version Control with GitHub: Part 4: Markdown and Code

Learning Version Control with GitHub

Markdown and Code

As discussed in the previous section, 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.

Before the new file was added in the previous section, however, there was already a file there. When the project was forked (cloned from another source), this file was carried forward from the original to the current repository. This was the README file.


Screenshot 2018-10-03 12.19.46

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.


Screenshot 2018-10-03 12.28.42

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.

Screenshot 2018-10-03 12.56.37

Markdown supports many of the same ideas of languages like HTML. It has multiple levels of headings.

Screenshot 2018-10-03 12.56.46

It supports giving text emphasis and making it bold as well.

Screenshot 2018-10-03 12.36.36

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

Markdown - Added Markdown

Open the README file with Atom 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.

GitHub Desktop - Markdown Usage

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.

Screenshot 2018-10-03 12.58.48

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

Screenshot 2018-10-03 13.00.53

While most changes should happen through something like the GitHut 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.

Screenshot 2018-10-03 13.03.59

Because GitHub understands markdown, editing files written in the language allows for seeing a preview of those changes.

Screenshot 2018-10-03 13.07.11

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.