For a complete Kramdown reference, see the GitLab Markdown Kramdown Guide. The gitlab-kramdown Ruby gem plans to support all GitLab Flavored Markdown in the future, which is all Markdown supported for display in the GitLab application itself. For now, use regular Markdown and follow the rules in the linked style guide. You can apply character formatting to a range of inline text with the following Markdown syntax.
- Github Markdown Syntax Support
- Github Markdown Code Syntax Highlighting
- Gitlab Markdown Code Block
- Gitlab Markdown Color Text
Markdown Syntax
What is Markdown?
Markdown is a lightweight text markup syntax. A key design objective of Markdown was to provide a syntax that can be easily be converted to web pages and rich text documents, but would also be readable - a human reading Markdown should be able to understand the content.
Markdown is not a single standard, and many variants exist.
Markdown on Gitlab
GitLab uses a specific variant of Markdown called GitLab Flavored Markdown, which extends the original [Markdown] syntax following the CommonMark Specification specification.
Basic Markdown Syntax
Bold Text: **Bold Text**
Italic Text: _Italic Text_
Headers and Structure
GitLab uses standard Markdown notation for headers: # Header 1 produces a Heading level 1, ## Header 2 produces a second level header, etc.
In Gilab, all Markdown-rendered headers automatically get IDs, which can be linked to, except in comments.
Lists
- Bulleted Lists:
* Bullet 1
- Enumerated Lists:
1. List item 1
Links
Link to another pages in the Wiki: [another page](pagename). Note these may be hierarchical using subfolders: examples of use of hierarchy are here.
Link to an external web page: [external page](https://www.opengroup.org)
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.
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.
Github Markdown Syntax Support
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.
Github Markdown Code Syntax Highlighting
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:
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.
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:
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! Jeilin driver download for windows. Check outour Markdown Guide for more resources, examples and applications and use your creativity to createbeautiful posts, with great styles!
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.
Gitlab Markdown Code Block
Happy markdowning!
Gitlab Markdown Color Text
Follow @GitLab and stay tunned for the next post!