AlexAtkinson/advanced_markdown.md

## advanced_markdown.md

      
    Raw
  

              advanced_markdown.md
            
          
    Advanced Markdown Usage Cheatsheet

Github Flavoured Markdown

Github markdown is not strictly markdown (though, what is...?), and is referred to as Github Flavoured Markdown, making previewing .md files necessary to ensure you're getting what you intend.
Use the GitHub Markdown Preview extension.
Examples


NOTE: Some or all of these examples may work elsewhere. Validate portability.


details
Create an expandable section.
Example:


foo
bar


blockquotes
Symbol: >
Example:

hi


pre, kbd & samp
Use the '<kbd>' tag to display a key representation, such as ctlr+z.
Use the '<samp>' tag to display sample output.

The following demonstrates nesting '<kbd>' and '<samp>' in '<pre>' (not possible in code blocks) to emphasize the command in a terminal representation.
[user@laptop ~]# cmd
hello world


header links
Link to headers.
Handling notes:

Link id's all start with # regardless of header level
Header content is normalized to automatically create the id

Punctuation is removed
All lowercase
Spaces convert to hyphens
double or more hyphens convert to a single hyphen
duplicate id's increment with a digit starting at '1'


Example:
### Awesome Header

[link to awesome header](#awesome-header)


anchor links
Links to anchors anywhere in a document.
Example:
foo<a name="foo"></a>

See [here](#foo) for more on foo.


html & divs
See the following for examples of fancy markdown pages that take full advantage of Github's support for HTML and Divs.

trinib
vishnudas-bluefox


footnotes
Example:
Here is a simple footnote¹. With some additional text after it.
The Code:
Here is a simple footnote[^1]. With some additional text after it.
[^1]: [Foo Reference](#example-footnotes)

Note that the footnote appears at the bottom of the markdown when rendered, as "Foo Reference" does for this example.


emojis
Github renders emojis such as 😄, or . The item to note  here is that your OS does not support all Github emojis, which causes ':trollface:' not to render it's respective icon in editors such as VSCode. This is due to the fact that they are not included in the unicode spec... yet?

See here for a complete list of supported emojis, including the Github Custom Emoji set.
Install the Markdown Emoji extension for VSCode to enable the preview of unicode emoji's in VSCode.


definition list
Create definition lists such as this:

Foo
Bar

Example:
<dl>
  <dt>Foo</dt>
  <dd>Bar</dd>
  <dt>Bar</dt>
  <dd>Foo</dd>
</dl>

While these are the highlights, there's more you can do, and there's no guarantee it's all documented anywhere. Reference the sanitization code to verify whether a tag is available in Github Flavoured Markdown.
Markdown Lint (VSCode)

Install the markdownlint extension.
Create a '.markdownlint.json' file in the root of your project directory, or any subdirectory to manage controls for that scope. For example, you might disable line-length and no-inline-html:
{
    "line-length": false,
    "no-inline-html": false
}
Specific violations can be ignored by embedding the appropriate configuration directly in a markdown file:
<!-- markdownlint-disable MD036 -->

**Table of Contents**

<!-- markdownlint-enable MD036 -->
This utility offers a lot of capability. Being aware of the Rules and Configurations available will allow you to make the most of it:
Accessibility

It is highly recommended to invest the time into making your MD files accessible. Have a look at the following resources for more on this topic.

Improving the Accessibility of Your Markdown
Accessibility in Github with GHL

Markdown Table Extension (VSCode)

This extension adds a lot of functionality to VSCode when editing tables.

Read the description for full details.
Mermaid Diagrams

Use Mermaid for text-driven diagram creation.
Get Preview Support (VSCode)

Install the Markdown Preview Mermaid Support extension.
Pretty Contact Links

Markdown is generally unkind to image manipulation, so the bottom alignment here is baked into the image itself.
You can either include the email icon and the name, or the name and multiple contact details below it using a definition list to provide nice formatting.
  Santa


  Santa
  
      santa@gmail.com

  951-262-3062
  

Note that because Github doens't support 'tel' href links, you cannot make the phone number clickable.

Note additionally that because markdown makes every image clickable, the best we can do with that is to link to the image id itself.


code
<dl>
  <dt>Santa</dt>
  <dd>
    <a href="mailto:noreply@gmail.com"><img src="https://user-images.githubusercontent.com/2965366/202583226-3f13a5d5-f9cb-442d-81aa-547cf209ef27.png" width='18' hspace='4px'/></a>&nbsp; santa@gmail.com<br>
<a href="#santa-phone"><img id=santa-phone src="https://user-images.githubusercontent.com/2965366/202583227-f96534fa-05fa-4bf6-affb-d6128b5235e2.png" width='16' hspace='5px'/></a>&nbsp; 951-262-3062
  </dd>
</dl>


BONUS: GFL Email Link Subject Population
GFL supports injecting email link subjects via query strings. For example:
[Email Link](mailto:noreply@google.com?subject=[GitHub]%20Example%20Subject)


Footnotes


Foo Reference ↩