For those who are used to write in Markdown or are beginning to learn this language, we are here to provide you some tricks and tips that may help you to think outside the box and make some “magic” when writing your files.
Markdown Tips & Tricks - Part 1
On the next post, we are going to show you how to embed videos on your markdown files. This second part will be published at October 26th.
For markdown basics, you can check this GitHub article, which provides us with a bunch of very often applied markup.
All the examples given below were tested on our Blog written in Jekyll, hosted by GitHub Pages, within a
gh-pages branch for a
project website. Depending on your server or on the way your site is build, some of these tips might not work. Anyway, feel free to give them a try, even if your markdown files don’t have the same configuration or compilation.
_config.yml settings are the following:
The tips provided by this post worked very well using Kramdown with GFM and Rouge. It works fine when replacing
pygments too. Other markdown and highlighters haven’t been tested yet, but you are more than invited to give it a try and tell us if works or not!
Our build has been made by running
bundle exec jekyll serve --safe on the command prompt, at the local root folder, as recommended by GitHub. Using the
--safe mode allows you to build your site locally in the closest way that GitHub will do it, avoiding building errors when uploading your files to GitHub.
It seems to have a bug on GitHub Pages regarding the
--safe flag! So, for now, we recommend you to serve Jekyll with Bundler without this flag, at least until they fix it. Run
bundle exec jekyll serve and watch for changes running
bundle exec jekyll serve --watch.
default.html file (where the markdown posts are called to) is placed at our
_includes folder and is a
HTML5 document. Our styles are written in
Adding HTML Elements
Let’s begin with new elements. Did you know you can add
HTML elements to your markdown? For example, if you need a horizontal line, you can add it as the code below:
Some text here
// blank line
// blank line
Something else here
…and will be compiled to…
Note that we left the lines
4 empty, this is a condition for
html elements to be untouched when your markdown is compiled.
Now you can freely style your
<hr> in your
Just to let you know, in this particular case you can use just a sequence of
----- onto your markdown and it will produce a
<hr> tag when compiled to html. But sometimes you can’t run from using some
html tags themselves in order to have the results you want.
Feel free to use the tag `` the same way for breaking lines.
Don't forget to leave a blank line between some regular markdown text and a html tag, otherwise you might face errors during files compilation!
Following the same logic,
HTML 5 allows you to add some extra elements, and you are also free to make up your own. We have added a few custom elements to this blog. For example, as you might have noticed, some of our titles on this blog are
This is not a
<span> tag. Actually, we made a new element up, called
<mkp-blue>. You can call elements whatever you want. This element has only one propriety defined in our
CSS, all the others are inherit from its parent element:
We can use these new elements combined with markup, for example, this line:
…will be compiled to:
…and this is going to be the result displayed on users’ browsers:
Hello! I'm a
BUT, you can’t do the opposite, using a markup within an html tag, like:
… as it will be compiled to:
… and will produce this result:
Hello! I'm a
… which probably is not what you want.
The good news is, with Kramdown you can do that by adding this markup before the section you want to combine HTML and markdown markup:
It will allow you to do crazy stuff like:
… which will produce:
Hello! This is gonna be bold! And this, blod and blue!
Then, if you need, you can close the HTML/Markdown block parser with:
That’s it, you can add as many default or non-default elements to your markdown file, as long as you leave blank lines above and below them.
Making up your own custom elements is not recommended when you want to stick to the standards. Also, they haven’t cross-browser compatibility. There is an article where the author goes deep into this subject. The minimum recommendation is adding this code to the site
<head> when you use them:
This will create a new element when the http request to your site is comming from Internet Explorer 9.
Adding HTML Divs
Exactly as we just have done, you can add some html divs to your markdown. And with divs, you can do pretty much anything you like, such as giving classes, ids, transitions, and anything that a regular
<div> tag supports in
For example, let’s say you want a particular image style at some point, you can just wrap it into a
<div> and that’s it!
The result will be exactly as expected:
And you customize your special image as you want, for example:
Here is the result:
Of course we could have styled the image itself in this case, but sometimes we need nested elements in order to produce the results we want. A very common case is giving an element a
position="relative" and its nested element a
position="absolute". We cannot achieve the same results by playing around just with one of them, we’ll need them both!
Applying HTML Classes
When I first started writing in markdown, I googled something like “how to apply classes to markdown” and couldn’t find much. BUT, when I tried something unusual, for my best surprise, it worked!
For example, let’s say you want to apply a different class to a paragraph. Instead of writing the regular text on markdown, as:
… you are free to write it as a
<p>...</p> HTML tag, like:
<p class="myclass">Hello! I'm a regular HTML paragraph written in a markdown file!</p>
… and it will be compiled to:
… and will be displayed on the browser like:
Hello! I'm a regular HTML paragraph written in a markdown file!
The only difference is that we have applied a new class to the paragraph, giving it a bluish background. But you can style your tags according to your needs!
That’s it! As simple as it looks! This way you are free to style your
HTML tags compiled from your markdown files however you want!
Just do not forget to always leave a blank line between your markdown regular text and any
I’ve just found out an easy way to applying classes to your markdown markup with Kramdown!! Look at that:
I’m in a green box now!
This was simply achieved by this piece of code:
It’s awesome, isn’t it?!
What if I need more than one
What if I need an
What if I need both, an
id and a
What if I need to add a
.class to an image?
I just loved this! Check the full reference out!
All right then, now that you know that you can add html elements and apply classes to them in markdown files, it’s time to make it work for you! Go on and use them freely, you’ll see that the results are fantastic and at the same time we keep the astonishing advantages of writing in markdown!
Don’t lose our next post, where we will show you how to embed videos in markdown files. It can be a little tricky, specially giving them responsiveness, but we are here to share our knowledge with you!
That's all folks!
We hope to have been helpful! Please, if you enjoyed this article, share it, recommend it or leave a comment to let us know!
If you have any questions or suggestions, please feel free to get in touch with us by filling our contact form.
Thanks for reading! Check our next article Markdown Tips and Tricks - Part 2!
- ☆ GitHub
- ☆ GitHub Pages
- ☆ Jekyll
- ☆ GitHub Flavored Markdown
- ☆ Jekyll Documentation
- ☆ Markdown
- ☆ Kramdown
- ★ Art work: Virtua Creative
- ★ Illustrations: we have downloaded from Freepik the original box and the original bulb.
Last update: 04/10/2016 - 19:32h.