How to retain HTML formatting in GitHub readme file upon upload? - html

Question

So i formatted the README.md file of a particular GitHub project using HTML as I found markdown to be quite limiting. Maybe I am not quite well versed with markdown or I prefer HTML, I am not sure. So the issue is, I have the README.md file on my local system and when I display it on browser using a Markdown plugin from Sublime Text, it shows up exactly as I want. But when I push the local README.md file to the server and try to view it in website, the formatting is lost completely.
Local formatting -
GitHub website view -
As you can see, the two files are totally different. How can I preserve the formatting once it is uploaded on the GitHub server ?
The following is the spaghetti HTML code. It is very ugly. I was in a hurry and so ended up with such ugly code violating every aspect of DRY. Please excuse that for now.
<div class="header" style="width: 100%; display: flex;">
<div style="font-size: 50px; font-family: arial; width: 50%;"> Blind Reader</div>
<div style="width: 50%; text-align: right; display: table; ">
<span style=" letter-spacing: 5px; padding-left: 150px; font-family: verdana; font-size: 11px; display: table-cell;vertical-align: middle ; width: 20px;"> Developers </span>
<img src="images/dev1.png" style="height: 60px; width: 60px;">
<img src="images/dev2.png" style="height: 60px; width: 60px;">
</div>
</div>
<div class="badges-container">
<div class="badges-body">
[![Ask Me Anything !](https://img.shields.io/badge/Ask%20me-anything-1abc9c.svg?longCache=true&style=plastic)](https://GitHub.com/Naereen/ama) [![made-with-python](https://img.shields.io/badge/Made%20with-Python-blue.svg?longCache=true&style=plastic)](https://www.python.org/) [![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg?longCache=true&style=plastic)](https://github.com/Naereen/StrapDown.js/blob/master/LICENSE) ![PyPI - Status](https://img.shields.io/pypi/status/Django.svg?style=plastic) ![Contributor](https://img.shields.io/badge/Contributors-2-orange.svg?longCache=true&style=plastic)
</div>
</div>
<div class="body-content">
<span style="font-size: 25px; font-family: verdana; color: #64686d;"> Welcome to the <span style="color: #18529b;">Blind Reader</span> project !</span>
<br>
<br>
<div style="font-size: 18px; font-family: verdana; text-align: justify;" class="introduction">Blind Reader is a portable, low-cost, reading device made for the blind people. The Braille machines are expensive and as a result are not accessible to many. <strong>Blind Reader </strong>overcomes the limitation of conventional Braille machine by making it affordable for the common masses. The system uses OCR technology to convert images into text and reads out the text by using Text-to-Speech conversion.The system supports audio output via Speakers as well as headphone. The user also has the ability to pause the audio output whenever he desires. It also has the facility to store the images in their respective book folder, thereby creating digital backup simultaneously. With this system, the blind user does not require the complexity of Braille machine to read a book. All it takes is a button to control the entire system !
</div>
<div class="dependency" style="font-family: verdana; font-size: 18px; padding-top: 30px;">
<span style="font-size: 30px; font-family: verdana; font-weight: 500;">Dependency</span>
<div style="background:#757a79;height: 1.2px; width: 100%"></div><br>
<span style="font-size: 18px; font-family: verdana; font-weight: 600;">Hardware Requirements:</span><br>
<ul>
<li>Raspberry Pi 3B.</li>
<li>Pi Camera.</li>
<li>Speakers / Headphones.</li>
<li>Push buttons - 2.</li>
<li>LDR - 1.</li>
<li>LED - 4.</li>
<li>Power supply - 5V,2A.</li>
</ul>
<span style="font-size: 18px; font-family: verdana; font-weight: 600;">Software Requirements:</span><br>
<ul>
<li>Python 3.</li>
<li>Python Dependencies:</li>
<ul>
<li>Rpi.GPIO</li>
<li>Pygame library.</li>
<li>picamera library.</li>
<li>google-cloud.</li>
<li>time.</li>
<li>os.</li>
<li>datetime.</li>
</ul>
<li>Google Cloud API - Vision , Text-to-Speech</li>
</ul>
</div>
<div class="code" style="font-family: verdana; font-size: 18px; padding-top: 30px;">
<span style="font-size: 30px; font-family: verdana; font-weight: 500;">Usage</span>
<div style="background:#757a79;height: 1.2px; width: 100%"></div><br>
</div>
<div class="usage-content" style="font-size: 18px; font-family: verdana; text-align: justify;">
<ul>
<li>
Use the following code to install the Google cloud python dependency.<br><br><code>pip3 install --upgrade google-api-python-client<br>pip3 install --upgrade google-cloud-vision<br>pip3 install --upgrade google-cloud
</code><br><br>
Use : Google CLoud Vision API for further Details.<br><br>
</li>
<li> Activate <strong>Cloud Vision API</strong> and <strong>Google Cloud Text-to-Speech API</strong> by visiting the dashboard and download the Service account credentials (Json file).</li>
<br>
<li>
Connect the hardware as follows:
<ul>
<li>
Pi Camera --> Camera Slot in Raspberry Pi 3.
</li>
<li>
Pair Bluetooth Speaker / Insert headphone into Raspberry Pi 3 audio jack.
</li>
<li>
LDR --> GPIO 37.
</li>
<li>
4 LEDs - GPIO 29 , 31 , 33 , 35 respectively.
</li>
<li>
Push Button 1 ( Camera capture ) --> GPIO 16.
</li>
<li>
Push Button 2 ( Play/Pause audio ) --> GPIO 18.
</li>
</ul>
<br>
<li>
Use the following code to start the system:
<br>
<code>
python3 //path/to/your/final.py/file
</code>
</li>
<br>
<li>
Place the image to be read under the camera and press <code> Button 1 </code> to read out a page.
</li>
</ul>
</div>
<div class="system-images" style="font-family: verdana; font-size: 18px; padding-top: 30px;">
<span style="font-size: 30px; font-family: verdana; font-weight: 500;">Demonstration</span>
<div style="background:#757a79;height: 1.2px; width: 100%"></div>
</div>
<div class="image-cotainer" style="display: flex;">
<div class="image1" style="width: 50%"> <img src="images/system1.jpg" style="width: 80%;"></div>
<div class="image2" style="width: 50%"> <img src="images/system2.jpg" style=" width: 80%; height: 80%; padding-top: 40px;"></div>
</div>
<div class="resources-section" style="font-family: verdana; font-size: 18px;">
<span style="font-size: 30px; font-family: verdana; font-weight: 500;">Resources</span>
<div style="background:#757a79;height: 1.2px; width: 100%"></div>
</div>
<div class="resources-container" style="font-family: verdana; font-size: 18px;">
<ul><br>
<li>
Google Cloud Platform.
</li>
<li>
Pygame python library.
</li>
<li>
Raspberry Pi.
</li>
<li>
Python.
</li>
</ul>
</div>
</div>
I have also takena look at this link. It lists all the tags that are whitelisted by GitHub. And as I can see almost all the tags I have used are present here.
Please help.

Answer 1

GitHub documents there markup filtering in the github/markup repo:
This library converts the raw markup to HTML. See the list of supported markup formats below.
The HTML is sanitized, aggressively removing things that could harm you and your kin—such as script tags, inline-styles, and class or
id attributes. See the sanitization
filter
for the full whitelist.
Syntax highlighting is performed on code blocks. See github/linguist
for more information about syntax highlighting.
The HTML is passed through other filters in the html-pipeline that add special
sauce, such as
emoji,
task
lists,
named
anchors,
CDN caching for
images,
and
autolinking.
The resulting HTML is rendered on GitHub.com.
Note that step 1 is were the Markdown processing happens and that most likely returns the results you expect. The problem starts with step 2. Github takes the HTML returned in step 1 and sanitizes it extensively. This sanitation happens regardless of whether the source was Markdown, rst, texttile, asciidoc, or any number of other source formats.In other words, these filters have no direct relation to Markdown. So your Markdown is probably fine.
Given the extensive sanitation filters, any benefits of using Markdown's raw HTML fallback are almost completely lost. Generally, I stick to plain Markdown in any document I expect to be rendered by GitHub as most anything that gets stripped by the filters would not be possible with plain Markdown anyway.
If you really want to find some workarounds, then you will need to study the sanitation filter yourself to see if there is any way to get what you want. I expect most of what you want will not be possible though.