| title | author | date |
|---|---|---|
Using HTML with GitHub |
Will Gammerdinger |
October 24th, 2022 |
Contributors: Will Gammerdinger
GitHub's Markdown format supports a limited amount of HTML formatting. The goal of this reference is to provide users of GitHub Markdown with a reference that they can use when using HTML within GitHub's Markdown.
The basic syntax of HTML will look like:
<tag>Text you want that tag applied</tag>.
You can think of the first <> as "opening the tag" and </> as "closing the tag".
The first few subsections will discuss formatting that can easily be done in GitHub Markdown. However, if you are working within a larger HTML code chunk it is best to use HTML formatting for all parts of that HTML code chunk, thus we need to discuss these essential formatting tools in HTML.
You could be accustomed to using **in order to initiate bold in GitHub Markdown. However, you can also do this in HTML by using <b> before the text you would like to be bold and </b> following the text you would like to be bold. The syntax would look like this:
<b>Text that you want to be bold</b>
Which appears as:
Text that you want to be bold
In order to do italics in HTML, you need to use <i> to initiate the italics and </i> to close the italics. The syntax would look like:
<i>Text that you want to be italicized</i>
Which appears as:
Text that you want to be italicized
Underlining text in HTMl requires that you use <ins> to initiate underlining and </ins> to close underlining. The syntax would look like:
<ins>Text that you want to be underlined</ins>
Which appears as:
Text that you want to be underlined
To initiate subscript you need to use <sub> and to close subscript you need to use </sub>. The syntax would look like:
H<sub>2</sub>O
Which appears as:
H2O
To initiate superscript you need to use <sup> and to close subscript you need ot use </sup>. The syntax would look like:
F<sup>2</sup>
Which appears as:
F2
To intiate a hyperlink you need to use <a> and to close a hyperlink you need to use </a>. Additionally, within the <a> tag you will need to place the href= option and then place your URL link in double quotes after it. The text you would like to appear to click on for the hyperlink will be between the <a> and </a>. The syntax would look like:
<a href="https://bioinformatics.sph.harvard.edu/training">HBC Training Webpage</a>
Which appears as:
To initiate a blockquote you need to use <blockquote> and to close a blockquote you need to use <blockquote>. The syntax would look like:
<blockquote>
Sometimes we need to blockquote text. Blockquoting text can have several purposes, perhaps we are adding a note about a command or we are quoting our favorite celebrity, Olivia Colman.
</blockquote>
Which appears as:
Sometimes we need to blockquote text. Blockquoting text can have several purposes, perhaps we are adding a note about a command or we are quoting our favorite celebrity, Olivia Colman.
In order to insert a keyboard looking key, we need to intiate it with <kbd> and close it with </kbd>.The syntax would look like:
<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>Delete</kbd>
Which appears as:
Ctrl + Shift + Delete
Formatting in HTML is oftentimes quite flexible and you can nest one formatting tag within another. For example if you wanted your text to be bold and underlined you could use:
<b><ins>Text that you want to be bold and underlined</ins></b>
Which appears as:
Text that you want to be bold and underlined
You may be interested in displaying code in HTML. Similarly, to how GitHub Markdown has ` for in-line code and ``` for code blocks, HTML has <code> for in-line code and <pre> for code blocks.
You can initiate in-line code with <code> and close in-line code with </code>. The syntax would look like:
Change directories to your favorite pictures directory by using: <code>cd /my/favorite/pictures/</code>
Which appears as:
Change directories to your favorite pictures directory by using: cd /my/favorite/pictures/
To initial a code block in HTML, you need to use <pre> and </pre> terminates a code block. The syntax would look like:
To see the contents of your favorite pictures directory:
<pre>cd /my/favorite/pictures/
ls</pre>
Which appears as:
To see the contents of your favorite pictures directory:
cd /my/favorite/pictures/ ls
HTML is has some special characters that it is picky about. The table below displays the special characters and what you should use in their place in HTML.
| Character | HTML |
|---|---|
| < | < |
| > | > |
| ' | ' |
| " | " |
| & | & |
| Tab |   |
| # | # |
Their syntax would look like:
As Lisa recounted the story, "Marge said 'Homer, don't you know that 3 < 4 & also that 3 > 1?'"
Which appears as:
As Lisa recounted the story, "Marge said 'Homer, don't you know that 3 < 4 & also that 3 > 1?'"
To add breaks/new lines use <br>. The syntax would look like:
Text 1<br>
Text 2<br><br>
Text 3
Which appears as:
Text 1
Text 2
Text 3
In order to add thematic, which are light lines that go across the page to break up sections, we need to use
. The syntax would look like:
Section 1
<hr />
Section 2
Which appears as:
Section 1
Section 2
To add headers use <h1>, <h2>, <h3>, <h4>, <h5> and <h6>. The syntax would look like:
<h1>Header 1</h1>
<h2>Header 2</h2>
<h3>Header 3</h3>
<h4>Header 4</h4>
<h5>Header 5</h5>
<h6>Header 6</h6>
Which appears as:
NOTE: It does not appear that you can go further than <h6>.
You could be interested in making bulleted lists without numbers (Unordered Lists) using <ul> or list with numbers (Ordered Lists) <ol>.
To make a bulleted list without numbers (Unordered List) You will need to initiate the unordered list with <ul> and close the unordered list with </ul>. Each bullet in the unordered list is going to need to start with a line item tag <li> and then close with <li>. The syntax would look like:
Items I need from the grocery store:
<ul><li>Milk</li>
<li>Eggs</li>
<li>Cereal</li></ul>
Which appears as:
Items I need from the grocery store:
- Milk
- Eggs
- Cereal
Ordered lists function similarly to unordered lists except you initiate ordered lists with <ol> and close them with </ol>. Like unordered lists they still need each list item to be initiated with <li> and closed with </li>. The syntax would look like:
The definitive ranking of best colors is:
<ol><li>Red</li>
<li>Green</li>
<li>Blue</li></ol>
Which appears as:
The definitive ranking of best colors is:
- Red
- Green
- Blue
Sometimes you might want to put a sub-bullets to a bulleted item. This follows all of the same syntactical rules we have discussed and your new list needs to be intiated and closed prior to the larger list being closed. The syntax for would like:
My unordered list:
<ul><li>List Item 1</li>
<li>List Item 2</li>
<ul><li>Sub-list Item 1</li>
<li>Sub-list Item 2</li>
<li>Sub-list Item 3</li></ul>
<li>List Item 3</li></ul>
Which appears as:
My unordered list:
- List Item 1
- List Item 2
- Sub-list Item 1
- Sub-list Item 2
- Sub-list Item 3
- List Item 3
Tables are a useful way of organizing data. You will need to initiate a table with <table> and close a table with </table>. Each row will need to be initiated with <tr> and closed with </tr>. If the elements of the table are headers, then they can be initiated with <th> and closed with </th>. While elements of data in a table that aren't headers are initiated with <td> and closed with </td>. Elements that are table headers get slightly different formatting than normal table data elements. The syntax would look like this:
My Table:
<table>
<tr>
<th>Header 1</th>
<th>Header 2</th>
<th>Header 3</th>
</tr>
<tr>
<td>Data 1 for Header 1</td>
<td>Data 1 for header 2</td>
<td>Data 1 for Header 3</td>
</tr>
<tr>
<td>Data 2 for Header 1</td>
<td>Data 2 for header 2</td>
<td>Data 2 for Header 3</td>
</tr>
</table>
Which appears as:
My Table:
| Header 1 | Header 2 | Header 3 |
|---|---|---|
| Data 1 for Header 1 | Data 1 for header 2 | Data 1 for Header 3 |
| Data 2 for Header 1 | Data 2 for header 2 | Data 2 for Header 3 |
You might be interested in inserting an image. To do this, initiate the image with <p> and close the image with </p>. However, in your <p> you are also going to need to specifiy your alignment for the image (i.e. would you like the image left-aligned, center-aligned or right-aligned. The default is a left-alignment.
Between your <p> and </p> you will need to open up <img> tag and and provide the indirect path from your current position to the image on GitHub to the src option along with the width in pixels that you would like to use to the width option. The syntax would look like:
<p align="center">
<img src="img/breakfast_Monvej.png" width="700" >
</p>
Which appears as:
If you want to add formulas, GitHub now has syntax for doing this, however there aren't great HTML options for this. Currently, there is one option that has been working for me. You can go to CodeCogs and write the expression that you would like to have rendered into the equation editor box and select the orange box to be "HTML". This will convert it into the HTML code you need to render your equation. You can click the generated HTML code and paste it into your GitHub Markdown. Euler's Identity would look like:
<img src="https://latex.codecogs.com/svg.image?e^{i\pi}+1=0" title="e^{i\pi}+1=0" />
Which appears as:
This isn't super clean as it is an image link from a different website, rather than being generated internally in GitHub and so if this site stops working, then the equations will as well. However, it appears to work for now, so until it breaks we can try to use this method when we need to put equations within HTML.
One neat aspect that HTML offers that we can't do in GitHub's Markdown is use dropdown menus. These collapsible menus are great for allowing users to toggle information. All of the formatting that we've used up to this point is all able to be used within these dropdown menus. To initiate a dropdown menu use <details> and to end a dropdown menu use </details>. When using a dropdown menu, you will likely want to have text for the user to click on in order to engage this dropdown. This text is initiated with <summary> and closed with </summary>. The syntax would look like:
<details>
<summary>Click here to expand the dropdown menu</summary>
You couldn't see this menu before, but now you can. Click the "Click here to expand the dropdown menu" again to hide this.
</details>
Which appears as:
Click here to expand the dropdown menu
You couldn't see this menu before, but now you can. Click the "Click here to expand the dropdown menu" again to hide this.Here is a nice page on nesting dropdowns.
This lesson has been developed by members of the teaching team at the Harvard Chan Bioinformatics Core (HBC). These are open access materials distributed under the terms of the Creative Commons Attribution license (CC BY 4.0), which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited.