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.
- Available input formats: kramdown (this is the default), markdown, or html. The input format GFM is available through the kramdown-parser-gfm gem.-o FORMAT, -output FORMAT. Specify one or more output formats separated by commas: html (default), kramdown, latex, man or removehtmltags. The converter pdf is available through the kramdown.
- Jan 19, 2016 Images, Jekyll, Kramdown, Markdown David Egan It’s often useful to add images in the body of a markdown document. While the featured image of a post or page can be specified in the YAML frontmatter, you can also call images directly within the markdown document.
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
Kramdown is a fast, pure Ruby Markdown superset converter, using a strict syntax definition and supporting several common extensions. With kramdown, creating a Table of Contents is the easiest thing ever! The automatic ToC will include every heading in the document, unless you don't want it to be included. You do not need to add anchors individually to every title. Online Kramdown Editor. Last but not least. You can also make use of Online Kramdown Editor to write Markdown documents. Compared to other editors mentioned above, this online editor is the poorest in terms of feature. No other online services are supported at all.
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
![Kramdown Kramdown](/uploads/1/1/8/5/118559566/186825528.png)
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:
Join me as we play Assassin’s Creed Syndicate Jack The Ripper DLC. Set twenty years after the conclusion to Assassin's creed Syndicate, we play as Evie Frye. Assassin%27s creed syndicate jack the ripper chests map. Assassin's Creed Syndicate - Jack the Ripper 100% Sync Guide A gameplay guide by Twisted-GIS. Published 29th December 2015. Updated 11th February 2016 This guide will help you achieve 100% synchronization in Jack the Ripper DLC to get the 'Ripperologist' gold trophy. This map is complete and has been checked. Whitechapel is a district in the East End of London. In Assassin's Creed Syndicate it is home to Bishopsgate station and Spitalfields market. The area was the location of the infamous Whitechapel Murders believed to involve Jack the Ripper in the late 1880s.
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:Kramdown Js
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!
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.
Happy markdowning!
Follow @GitLab and stay tunned for the next post!
A few things have changed in Jekyll 4.
Before we dive in, you need to have at least Ruby 2.4.0installed.
Run the following in your terminal to check
If you’re using a supported Ruby version >= 2.4.0, go aheadand fetch the latest version of Jekyll:
post_url
Tag and Baseurl
The
post_url
tag now incorporates the relative_url
filter within itself and therefore automatically prepends your site's baseurl
to the post's url
value. Please ensure that you change all instances of the
post_url
usage as following: Template rendering
We’ve slightly altered the way Jekyll parses and renders your various templatesto improve the overall build times. Jekyll now parses a template once, caches itinternally and then renders the parsed template multiple times as required byyour pages and documents.
The downside to this is that some of the community-authored plugins may not workas they previously used to.
Static files in unrendered collections
Collections other than
posts
can contain static assets along with Markdown files.But if the collection has not been configured with metadata output: true
, thenneither its documents nor its static assets will be output to the destinationdirectory.For plugin authors
- If your plugin depends on the following code:
site.liquid_renderer.file(path).parse(content)
,note that the return value (template
, an instance ofLiquid::Template
), from that line willalways be the same object for a givenpath
.
Thetemplate
instance is then rendered as previously, with respect to thepayload
passed to it.You’ll therefore have to ensure thatpayload
is not memoized or cached in your plugin instance. - If its a requirement that
template
you get from the above step be different at all times,you can invokeLiquid::Template
directly:
Exclusion changes
We’ve enhanced our default exclusion array.It now looks like the following:
What’s new is that this array does not get overridden by the
exclude
arrayin the user’s config file anymore. The user’s exclude entries simply getadded to the above default array (if the entry isn’t already excluded).To forcibly “process” directories or files that have been excluded, list themin the
include
array instead:The above configuration directs Jekyll to handle only
node_modules/uglifier/index.js
while ignoring every other file in thenode_modules
directory since that directory is “excluded” by default.Note that the default
include
array still gets overridden by the include
array in your config file. So, be sure to add .htaccess
to the list if youneed that file to be present in the generated site.Kramdown v2
Jekyll has dropped support for
kramdown-1.x
entirely.From
v2.0
onwardskramdown requires specific extensions to be additionally installed to usecertain features are desired outside of kramdown’s core functionality.Out of all the extensions listed in the report linked above, gem
kramdown-parser-gfm
is automatically installed along with Jekyll 4.0. Theremaining extensions will have to be manually installed by the user depending ondesired functionality, by listing the extension’s gem-name in their Gemfile
.Notes:
Kramdown Toc
kramdown-converter-pdf
will be ignored by Jekyll Core. To have Jekyll convert Markdown to PDFyou’ll have to depend on a plugin that subclassesJekyll::Converter
with therequired methods.For example:- Vendors that provide a versioned Jekyll Environment Image (e.g. Docker Image, GitHub Pages, etc)will have to manually whitelist kramdown’s extension gems in their distributions for Jekyll 4.0.
Kramdown Ruby
Deprecated Configuration Options
Kramdown Table
Jekyll 4.0 has dropped support for all legacy configuration options that were deprecated over multiplereleases in the previous series.
Kramdown Jekyll
To that end, we shall no longer output a deprecation warning when we encounter a legacy config key norshall we gracefully assign their values to the newer counterparts. Depending on the key, it shall eitherbe ignored or raise an
InvalidConfigurationError
error if the key is still valid but the associatedvalue is not of the valid type.