A One-Stop Guide to Markdown Styling
Readme files (or PRs) on github should be the least of a developer’s worries
As all my posts start; I needed to make ReadMe files for my github after years of avoiding them.
Turns out I don’t know as much markdown magic as I thought. Here’s an expanded list of tools and tricks that I will probably will need to reference again in the future;
The Tools — Atom Markdown Previewer
Viewing how your .md file looks before pushing it up to github is a very good idea — especially if you don’t want those commits increasing.
Use the ‘Markdown-preview-plus’ package on Atom to preview your page as you update your code.
ctrl-shift-m will toggle the preview tab beside your code for a side-by-side workspace.
The Actual Markdown Styling Guide
contains: font sizes, font style (bold, italics), bullet points, images, tables
Font Sizes
Use the HTML headers for titles and headers. Sizes 1 to 6 available with the largest being header 1 ie. ‘#this’
Font Style
Bold like this **I'm Bold**
Italicise like this *I am Italicised*
Bullet Points
list them in the .md file like so:
* point 1
* point 2
* point 3
and they will look like so:
Also, tabbing works the same way as to show nested bullet points
* point 1
<TAB> * point 2
<TAB><TAB> * point 3
which looks like this:
Links to other Websites
The description of the link is on the left, this will show up in the document.
[Click this Link.](https://www.google.com)
This will look like so:
Images
Images need placed inside the root directory or inside some directory within the root. This location will be referenced when calling it from the readme file.
Here’s an example:
The description is optional, it will display if the image is not found. You can just keep the square brackets without a description too.
The file path in the ‘()’ brackets lead to the image file. If I have the following structure,
Root Directory
— projectFiles.js
— projectFiles.html
— readme.md
— myImageFolder
— — myImage.jpg
And I want to preview on Atom, then I use a path like this:
And I want to send to GitHub, then I use a path like this:
The size boundaries are written with the ‘=123x’ or ‘=123x456’ format.
They specify how large the image will be in pixels. The first example ‘=123x’ doesn’t specify a height so the image is scaled by a width of 123px only while the height readjusts.
Tables
Tables are really helpful. Use this structure to show a table in .md files:
|ColumnName1|ColumnName2|ColumnName3|
| — — — — — — | — — — — — — | — — — — — |
|cell stuff|more contents|more contents|
|words|123.456|more words|
it will look like this
To change alignment of the cells you can use colons to specify center or right alignment on the table seperator:
|: — — — — — —: | — — — — — — :|: — — — — — |
The first column would be centered. The second, right aligned. And the thrid, left aligned or ie. normal.
Images and Tables
Images can be put into the tables in the same way;
|ColumnName1|ColumnName2|ColumnName3|
| — — — — — — | — — — — — — | — — — — — |
||||
Here’s an example of images within a table from one of my github projects:
Adding in Code
Code can be put into blocks and be specified. Github’s Jekyll md processor adds syntax highlighting on these code blocks to make code more readable.
Here’s an example for python. The same structure applies to other languages:
```python
# ex. comment, import, var, print
import pandas as pd
newVar = 30.5
print(“I am a string”)
```
That will then look like this:
—
And that should cover everything required for making markdown documents.
Now I can finally get back to coding, and hopefully, you can too :)
