JWS Docs / Markdown Intro

Markdown Basics

Headings

We make a heading by adding 1 to 6 # hash(UK) / pound(US) symbols before typing our heading text.

# creates a <h1></h1>

## creates a <h2></h2>

### creates a <h3></h3>

#### creates a <h4></h4>

##### creates a <h5></h5>

###### creates a <h6></h6>

Paragraphs

Paragraphs are groups of continual lines of text separated by a blank line. These are made in the same way as writing an email or document by hitting return/enter twice to make a blank line between the blocks of text.

You will then see these blank spaces separating your paragraphs when the markdown is converted.

Line Breaks

A line break is where we want shorter lines of text close
together like this, without a line space between them.
Unlike the gap we get when starting a new paragraph
as the next line shows.

We do this by adding two blank spaces at the end of the text line
where we want the break with the spacebar
before hitting return/enter and starting a new line.

Blockquotes

A blockquote is for text that is quoted from another source which is visually set apart from the flow of the page.

To format a blockquote in markdown we add a greater than symbol > at the beginning of the paragraph. If your quote spans more than one paragraph then you need to add it to the beginning of each paragraph, it can also be used in between to make a line space.

   > Explore stories, places and engineering marvels behind the railways 
   >
   > National Railway Museum - York

Explore stories, places and engineering marvels behind the railways
National Railway Museum - York

Emphasis & Bold

We can highlight text in our writing by either emphasising it with italic font or by making it bolder. To do this we use either asterisk * or underscore _ symbols before and after the text to be highlighted.

For italic emphasis we use single *asterisk* or _underscore_

For bold text we use double **asterisk** or __underscore__

We can also have Bold Italic Text with triple ***asterisk*** or ___underscore___

Horizontal Rule

If we want to put a visible divide between text we can add a hr, by placing three or more hyphens ‐, asterisks *, or underscores _ on a line by themselves.

Each of the following lines will produce a horizontal rule:

   ‐‐‐
   ***
   ___

Lists

We can have either ordered (numbers) or unordered (bullet points) lists.

Ordered

To create an ordered list before each list item we need to type a number followed by a period (full stop) . then a space

   1. list item one
   2. list item two

1. list item one
2. list item two

We can also nest list items too by indenting it with a tab or at least two spaces beneath the item above it.

   1. list item one
      1. nested list item one
      2. nested list item two
         1. second nested list item one
         2. second nested list item two
   2. list item two

1. list item one
   1. nested list item one
   2. nested list item two
      1. second nested list item one
      2. second nested list item two
2. list item two

Unordered

To create an unordered list before each list item we need to type a number followed by a asterisk * then a space

   * list item one
   * list item two

• list item one
• list item two

We can also nest list items too by indenting it with a tab or at least two spaces beneath the item above it.

   * list item one
      * nested list item one
      * nested list item two
         * second nested list item one
         * second nested list item two
   * list item two

• list item one
  • nested list item one
  • nested list item two
    • second nested list item one
    • second nested list item two
• list item two

Code

We can show code blocks by using the tick back symbol ` simply wrap the code with three tick backs before & after.

   ```
   <p class="shouty_text">Plus Much More besides!</p>   
   <h3>When & Where</h3>
   <ul>
      <li>Wednesday 15th September</li>
      <li>10am - 3pm</li>
      <li>Meet at museum main entrance</li>
   </ul>
   ```

Your code block will display like this

 <p class="shouty_text">Plus Much More besides!</p>

 <h3>When & Where</h3>

 <ul>

   <li>Wednesday 15th September</li>

   <li>10am - 3pm</li>

   <li>Meet at museum main entrance</li>

 </ul>

We can also add syntax highlighting to our code by adding a language identifier e.g HTML or JavaScript after the first three backticks.

   ``` html   
   <p class="shouty_text">Plus Much More besides!</p>   
   <h3>When & Where</h3>
   <ul>
      <li>Wednesday 15th September</li>
      <li>10am - 3pm</li>
      <li>Meet at museum main entrance</li>
   </ul>
   ```

Syntax highlighting will make your code block look something like this

<p class="shouty_text">Plus Much More besides!</p>
<h3>When & Where</h3>
<ul>
    <li>Wednesday 15th September</li>
    <li>10am - 3pm</li>
    <li>Meet at museum main entrance</li>
</ul>

The backtick ` is typically located on the same key as the tilde ~ on your keyboard. Here’s how you can find it on most UK and US keyboards, it’s in the top left corner, just below the Esc key and to the left of the number 1 key.

Links

External Links

We can add inline links by first wrapping in square brackets [ ] the link text we want people to see, we follow that with a set of parentheses ( ) where we add the URL.

There is also the option to add a title inside the parentheses after the URL which will then appear when you hover over the link.

This a link to [JWSOne](https://github.com/jasminedesign/jwsone "JWSOne")

This a link to JWSOne

Footnotes

Footnotes can be added to your document by using this syntax after the word or sentence you would like to add further notes to at the bottom of your document.

   Inside square brackets add a carat (or hat) followed by a reference number [^1]
   A footnote can have multiple lines [^2]
   You can also use named references too [^notes]


   [^1]: Then elsewhere in your document add your footnote 
     prefixed with the same square bracket/carat syntax followed with a colon :  
   [^2]: Every new line should be prefixed with 2 spaces e.g [^1] & [^notes]
   [^notes]: Please note - Named footnotes will still render with numbers 
     instead of the text but allow easier identification and linking.     

The position of a footnote in your Markdown does not influence where the footnote will be rendered. You can write directly below your reference to the footnote, and it will still be rendered at the bottom of the document.

Images

We can also display images in our document by using an exclamation ! followed by alt text wrapped in square brackets [ ] then followed by a link to the image wrapped in a set of parentheses ( ).

GitHub supports embedding images into your issues, pull requests, discussions, comments and .md files. You can display an image from your repository, add a link to an online image, or upload an image

   ![stephensons rocket](https://url_to_an_external_image_goes_here)

   ![stephensons rocket](/img/stephensonrocket.jpg)

Alerts

Alerts are an extension of blockquote that can be used when highlighting useful information such as Notes and Tips, or if you need to draw urgent attention to something with Important, Warning and Caution. Each alert is displayed in a blockquote and has a different colour highlight and accompanying icon.

   > [!NOTE]  
   > Highlights information that users should take into account, even when skimming.

   > [!TIP]
   > Optional information to help a user be more successful.

   > [!IMPORTANT]  
   > Crucial information necessary for users to succeed.

   > [!WARNING]  
   > Critical content demanding immediate user attention due to potential risks.

   > [!CAUTION]
   > Negative potential consequences of an action. 

Keyboard Commands

Across this page and throughout the tutorial we use the HTML keyboard command tag <kbd> to highlight when we need you to action a specific key or combination of keys.

To add a keyboard command in markdown we can also use the same HTML tag:

    Create a Save key
    <kbd>S</kbd>
    
    Create multi-key commands with a + symbol between each like this copy command
    <kbd>Ctrl</kbd> + <kbd>C</kbd> 

The above keyboard commands will look similar to these, though we have added extra styling within our CSS to make ours green.

S

Ctrl + C

Further Markdown

We have only included here some of the most commonly used markdown syntax, so if you haven't found what you were looking for or would like further information on what is referenced, then head to GitHub Docs Basic Formatting Syntax page.