Readme first!
Using kramdown, Jekyll’s default Markdown converter, you can mix HTML and Markdown. How does this work? If you want Markdown content inside block level elements to be converted to HTML, simply add the markdown='1' attribute to the opening tag of the block-level element. Most Markdown engines I've seen allow plain old HTML, just for situations like this where a generic text markup system just won't cut it. (The StackOverflow engine, for example.) They then run the entire output through an HTML whitelist filter, regardless, since even a Markdown-only document can easily contain XSS attacks.
kramdown was originally licensed under the GPL until the 1.0.0 release. However, due to the manyrequests it is now released under the MIT license and therefore can easily be used in commercialprojects, too.
However, if you use kramdown in a commercial setting, please consider contributing back anychanges for the benefit of the community and/or becoming asponsor or apatron - thanks!
Sponsors:
- GROSSWEBER provides softwaredevelopment consulting and training services.
Introduction
kramdown is a fast, pure Ruby Markdown superset converter, using a strict syntax definition andsupporting several common extensions.
The syntax definition for the kramdown syntax can be found in doc/syntax.page (or online athttp://kramdown.gettalong.org/syntax.html) and a quick reference is available indoc/quickref.page or online at http://kramdown.gettalong.org/quickref.html.
The kramdown library is mainly written to support the kramdown-to-HTML conversion chain. However,due to its flexibility (by creating an internal AST) it supports other input and output formats aswell. Here is a list of the supported formats:
- input formats: kramdown (a Markdown superset), Markdown, GFM, HTML
- output formats: HTML, kramdown, LaTeX (and therefore PDF), PDF via Prawn
All the documentation on the available input and output formats is available in the doc/directory and online at http://kramdown.gettalong.org.
Starting from version 1.0.0 kramdown is using a versioning scheme with major, minor and patch partsin the version number where the major number changes on backwards-incompatible changes, the minornumber on the introduction of new features and the patch number on everything else.
For information about changes between versions, have a look athttp://kramdown.gettalong.org/news.html or the commit history!
Usage
kramdown has a very simple API, so using kramdown is as easy as
For detailed information have a look at the API documentation of the Kramdown::Document class.
The full API documentation is available at http://kramdown.gettalong.org/rdoc/, other sites with anAPI documentation for kramdown probably don't provide the complete documentation!
There are also some third-party libraries that extend the functionality of kramdown -- see thekramdown Wiki at https://github.com/gettalong/kramdown/wiki.
Development
Just clone the git repository as described in doc/installation.page and you are good to go. Youprobably want to install rake so that you can use the provided rake tasks.
If you want to run the tests, the development dependencies are needed as well as some additionalprograms like tidy and latex. See the .travis.yml file for more information.
License
MIT - see the COPYING file.
If you use a markdown engine for writing your website content and you'd like tolearn a few tricks to have more freedom with it, this post is for you.
The markdown engine we use for about.GitLab.com is Kramdown, and that is the onewe'll be referring to on this post.
Jekyll Math
Note: We assume you already know what a markdown engine is and how it is applied to a website.
On this post
- Classes, IDs and Attributes
- HTML Blocks
Our Markdown Guide
Last week a lot of people were happy for our Handbook being open source, as we explainedin details on the post 'Our Handbook is open source: here's why'.Every GitLab Team member does touch our website, starting on his or her first weeks,as part of the onboarding tasks.Doesn't matter if he or she is an advanced programmer or never have seen an HTML code before,collaborating is the key for making sure we are all on the same side. And we love it!
One of our Handbook pages is a full Markdown Guide for the markupthat we use in our website, generated by Middleman.It brings a lot of details on how to use Kramdown for writing content.Every markdown page of this website, which is an opensource project available for peeking and contributing, can use anyof the rules explained there. This April we changed the markdown engine from RDiscount toKramdown, and not everybody in our Team knew the new 'magical' stuff we could use from this change. That'swhy we decided that writing a guide would be useful for those already used to markdown, andhelpful for those completely new to it.
Why Kramdown
Perhaps your first question will be something like 'okay, why is Kramdown so special?'. My firstexperience with markdown was when I first used a Static Site Generator, Jekyll. Coming fromprevious experiences in web development on PHP and HTML, the first thing I wanted to do to amarkdown post was adding a class to a particular heading. When I googled for that, I was prettydisappointed because apparently we aren't supposed to apply classes inline into markdown files.So, I had to experiment a lot until I got the desired result: add some color to my heading.
After trying a lot of new tweaks, and digging through the web for answers that insisted on not coming, I finallyfound out that with Kramdown, yes, I could do a lot of things. And finally I could apply some inline classesthrough my posts and have my blue headings when I wanted them blue. But at that time, I hadn't noticedthat we could do some really great magic with it, and that's what I'm sharing with you in this post.
The magic
We could say that the Kramdown magic concentrates to the following syntax: {: something}.This little devil is the basis of a lot of awesome resources.
Let's go over a few of them now, but you'll find a lot more in our Markdown Guide.
Classes, IDs and Attributes
Let's start with something classic, as the ability of applying CSS classes, custom IDs, and customattributes to the elements.
Applying classes
If you think of any CSS class, what comes into your mind first? I suppose it's something like:
Okay, we have a .blue class. Let's say once in a while we want a blue paragraph or a blue heading. Just do:
And of course, the output will be:
Output
This is a paragraph that for some reason we want blue.
And if we want a blue heading, we do exact the same thing:
And the output is going to behave as we expect it to:
Output
What if I want to apply two classes at the same time?
And the output will be as expected:
Output
As simple as that! The markup is simple and intuitive.
Now, guess what, we can do exactly the same for IDs!
Custom IDs
Kramdown itself will append an ID for each heading, automatically. The ID will be all the wordsin the heading together, connected by dashes. For the example above, 'A blue heading', the HTML output IDwill be a-blue-heading:
Let's say we want the ID called blue-h:
Will produce exactly what it's meant to (a blue heading with the custom ID):
So, the output would be:
Output
Note that we can attribute both class and ID in one markup, as in {: .class #custom-id}. But we can usejust one of them too: {: .class} or {: #custom-id}.
Interesting, isn't it?
Custom Attributes
Yes, we can go even further and apply any key/value pair we need:
We can use them, for example, for quickly applying general styles:
But they are specially useful for links, as in:
This way we can call a JavaScript function, for example:
Output
Table of Contents (ToC)
A ToC is so awesome and easy to produce. Have you noticed our ToCon this post? It's generated automatically by Kramdown with this simple markup:
Kramdown Ruby
All the file headings will be all automatically included in the ToC, except for those we don't want there.For these, we apply a class called no_toc, and Kramdown will respect our will:
And of course, we can make the ToC an ordered list instead of unordered:
Awesome, isn't it?
HTML Blocks
Whenever we need HTML blocks, we can use them freely!
In our Marketing Handbook you will find plenty of them.
Font Awesome
Font Awesome is a good use-case for HTML blocks within markdown files.
Check this!
Output
Iframes
We can embed anything within <iframe> tags, such as YouTube and Vimeo videos,Google and OneDrive documents and anything else available in iframes:
We are using the class video_container to make it responsive.
Output
CodePen
CodePens are really good for some cases, when you want to display codes and results, for example. Check this cute dog,created with HTML and Sass:
See the Pen Dog by Virtua Creative (@virtuacreative) on CodePen.
Mix HTML with Markdown
Yes, we definitely can do this! We need to add the following markup to the markdown document before mixing upHTML and markdown:
And we can close it any time, if necessary:
This is going to make this:
To be displayed like this:
Output
Something in markdown.
Then an HTML tag with crazy markup!
Blue boxes, like this one above, used to display the outputs on this post, were generated with this resource.
Kramdown Image
Styles
One of the most useful features is the ability to add <style> tags to our markdown file too!We can do that for simply styling our web page without affecting the entire site. Just go on and add thetag to any part of your markdown:
Kramdown Math
This tag was applied to this very document to exemplify this case, also to help with the classes describedearlier in this post.
Conclusion
There is a lot more you can do, mix, and bring together using Kramdown. It's awesome! Check outour Markdown Guide for more resources, examples and applications and use your creativity to createbeautiful posts, with great styles!
Kramdown Parser Gfm
Anything else you know of and is not in our Guide? Any new magic?Any trick? Please contribute by submitting an MR to thesource file. Your collaboration is much appreciated.
Kramdown Editor
Happy markdowning!
Kramdown Class
Follow @GitLab and stay tunned for the next post!