working-with-markdown

Working with Markdown

A short README.md that explains how to get started with Markdown, a super-simple markup language for web pages

Getting Started

  1. Login to GitHub.
  2. Click + to add a new repo.
  3. Enter the name of the repo (which will become the title of your page).
  4. Allow GitHub to create a .gitignore based on the type of project (if needed).
  5. Allow GitHub to draft a README.md.
  6. Choose a license if desired.

GitHub Pages

While viewing your new repository in GitHub, click the repo Settings icon (looks like a gear). Scroll down to GitHub Pages Section and change the drop down from “none” to “master branch” and click “Save”. Scroll back down to see the URL of your published site. Copy this URL and put it in the Webpage link in the first section under the title as shown above.

Editing README.md

You can edit README.md online by clicking on the file name and then the pencil icon OR you can install a text editor like VS Code.

If you use VS Code, the following extensions may be helpful:

Title and Section Headings

The first line will be the title and the only first-level heading in your document. Use a single hash to indicate the title and two hashes before each section heading.

Links are easy. Put the display name in square brackets first, and without leaving any spaces, put the URL in parentheses as shown in the links section above. If desired, include an image title within the parenthesis after your URL. Put the title in double quotes after your URL and leave a space between URL and title.

Ordered and Unordered Lists

Lists are easy. Put each list item on its own line, and separate each list with an empty line above and below.

For an ordered list, preface each item with a 1. and leave a space as shown above.

For an unordered list, preface each item with a dash and space as shown above.

Formatting Code

Code should be fenced using three backtics ` on the line above and the line below your code. After the opening backtics, put the syntax type, e.g. JavaScript or DOS (for Windows terminal commands) or Bash (for Git Bash commands).

dir

Displaying Images

It can be a bit challenging to find the correct URL for each image. Generally, store your embedded images in your repo if they are original, or reference the hosted location for the image if already available on the web. Images look like links with an ! in front, for example, an external image can be displayed as shown below. If desired, use a title as we did with links above. The URL must be to the image itself, so look for URLs that end with an image file extension, e.g., jpg, png, ico).

Hosted image

Displaying Local Images

You can also upload an image into your repo. To get the correct URL, upload the image to your repo. Then click on the image file in the repo. Get the URL of the image itself, and change blob to raw. As noted by win93:

While using /blob/ appears to work in the GitHub preview and repository view, the image does not load properly when you look at the published version. This change makes the image link to the true image, instead of the preview/lightbox (similar to the difficulty with Wikimedia).

vscode image

Paragraphs

Lines directly below one another will wrap into a single paragraph. Just as this sentence is merged onto the line with the sentence before.

If you don’t want text to flow together, leave a blank line between items you wish visually separated as done with the name and email address at the end of this document. Use the Preview mentioned below to check appearance before you commit your changes.

Preview Changes

If editing online in GitHub, scroll up to the top of the edit box, and click “Preview Changes” to see what your file will look like when displayed as a webpage.

Learn More

Learn more by checking out Mastering Markdown and other resources.

About

Denise Case

dcase@nwmissouri.edu

This site is open source. Improve this page.