Skip to content

Hack the markdown

Info

In most cases, you will not use the features described in this section, and you can skip them. This section was added to demonstrate that you will be not limited by standard or even Extended Markdown.

If you stumble upon the limitations of Markdown, you can use raw HTML, CSS, and even Javascript directly in your Markdown documents, greatly extending its functionality.

This section might convince you that Markdown (using MkDocs-MagicSpace) is the right choice to start. Because even if you hit the limitations of the extended Markdown sometime in the future, you will be able to solve it without the need to remake everything using another technology

Attribute lists

The Attribute Lists adds the ability to apply CSS styles to Markdown elemennts. It is very easy and convenient way to go beyond standard Markdown.

In order to apply attributes add block with {curly braces} after the element, use it to specify class names or css styles.

For example, text customized using attribute list 👇

Example

Do you know the difference between a car salesperson and a software salesperson? The car salesperson knows when they're lying.

```
Do you know the difference between a car salesperson and a software salesperson? The car salesperson knows when they're lying.
```{style="background-color: black; color: white"}

If you are using MkDocs-MagicSpace, MkDocs material theme is set up and you can style a link to another website to look like a button with Material design. You just need to list classes that should be applied to the link 👇

Style link as button

Visit our Github page 

[Visit our Github page :fontawesome-brands-github-alt:](hhttps://github.com/bluxmit/alnoda-workspaces){ .md-button .md-button--primary }

HTML & CSS inside Markdown

You can use HTML and CSS directly inside your Markdown document mixing them all together. This gives you the great power!

Now we can style the text as much as we want 👇

Styling text

Microsoft is working on software for self-driving vehicles I can't wait until my car suddenly stops in the middle of the highway and reboots to install updates. 

<span style="font-family: serif; color: #f59842; font-size: 1.2rem;">Microsoft is working on software for self-driving vehicles</span></br>
<span style="font-family: serif; color: teal; font-size: 0.8rem;">I can't wait until my car suddenly stops in the middle of the highway and reboots to install updates.</span>

A good idea is to combine HTML + CSS with Attribut lists. You can define CSS for some class in the <style> tag, and apply it many times to different obbjects.

Animated icon

<style>
@keyframes heart {
  0%, 40%, 80%, 100% {
    transform: scale(1);
  }
  20%, 60% {
    transform: scale(1.15);
  }
}
.heart {
  animation: heart 1000ms infinite;
  color: red;
  font-size: 2em;
}
</style>

:octicons-heart-fill-24:{ .heart }  :octicons-heart-fill-24:{ .heart }  :octicons-heart-fill-24:{ .heart }

Markdown inside HTML & CSS

By default, Markdown ignores any content within a raw HTML block-level element. But MkDocs MagicSpace has lots of plugins and extensions installed, so this is not a problem! The content of a raw HTML block-level element can be parsed as Markdown by including a markdown attribute on the opening tag.

For example, the checklist is left-centered:

  • One
  • Two
  • Three

Let's make it middle-centered by wrapping in the HTML

Markdown within HTML

  • One
  • Two
  • Three
<div style="display: flex; justify-content: center;" markdown="block">

- [X] One
- [X] Two
- [ ] Three

</div>

You can find more information about Markdown within HTML in this document

Modify MkDocs pages

You can use CSS to modify any MkDocs document page, for example, remove components you don't like. For instance, the Table of Content (TOC), which you can see on other pages was, removed from this page by adding the following snippet of code directly to the Markdown 👇

<style>
/* Remove TOC on this page */
.md-sidebar.md-sidebar--secondary {
    display: none;
}
</style>

Hint

There is a bettter way to remove TOC or navigation from any page - using metadata in the beginning of the page

---
hide:
- navigation
- toc
---

Go full crazy

Finally, you can include very sophisticated HTML, CSS and even Javascript code inside your Markdown documents

Author: Henrique Rodrigues (August 31, 2018)
Show the code
<style>
.wrapper {
  margin-top: 50px;
  margin-bottom: 5px;
  background-color: #ffc32b;
  width: 100%;
  height: 600px;
  border-radius: 5px;
}
.container {
  width: 300px;
  height: 280px;
  position: relative;
  top: calc(50% - 140px);
  left: calc(50% - 150px);
}
.coffee-header {
  width: 100%;
  height: 80px;
  position: absolute;
  top: 0;
  left: 0;
  background-color: #ddcfcc;
  border-radius: 10px;
}
.coffee-header__buttons {
  width: 25px;
  height: 25px;
  position: absolute;
  top: 25px;
  background-color: #282323;
  border-radius: 50%;
}
.coffee-header__buttons::after {
  content: "";
  width: 8px;
  height: 8px;
  position: absolute;
  bottom: -8px;
  left: calc(50% - 4px);
  background-color: #615e5e;
}
.coffee-header__button-one {
  left: 15px;
}
.coffee-header__button-two {
  left: 50px;
}
.coffee-header__display {
  width: 50px;
  height: 50px;
  position: absolute;
  top: calc(50% - 25px);
  left: calc(50% - 25px);
  border-radius: 50%;
  background-color: #9acfc5;
  border: 5px solid #43beae;
  box-sizing: border-box;
}
.coffee-header__details {
  width: 8px;
  height: 20px;
  position: absolute;
  top: 10px;
  right: 10px;
  background-color: #9b9091;
  box-shadow: -12px 0 0 #9b9091, -24px 0 0 #9b9091;
}
.coffee-medium {
  width: 90%;
  height: 160px;
  position: absolute;
  top: 80px;
  left: calc(50% - 45%);
  background-color: #bcb0af;
}
.coffee-medium:before {
  content: "";
  width: 90%;
  height: 100px;
  background-color: #776f6e;
  position: absolute;
  bottom: 0;
  left: calc(50% - 45%);
  border-radius: 20px 20px 0 0;
}
.coffe-medium__exit {
  width: 60px;
  height: 20px;
  position: absolute;
  top: 0;
  left: calc(50% - 30px);
  background-color: #231f20;
}
.coffe-medium__exit::before {
  content: "";
  width: 50px;
  height: 20px;
  border-radius: 0 0 50% 50%;
  position: absolute;
  bottom: -20px;
  left: calc(50% - 25px);
  background-color: #231f20;
}
.coffe-medium__exit::after {
  content: "";
  width: 10px;
  height: 10px;
  position: absolute;
  bottom: -30px;
  left: calc(50% - 5px);
  background-color: #231f20;
}
.coffee-medium__arm {
  width: 70px;
  height: 20px;
  position: absolute;
  top: 15px;
  right: 25px;
  background-color: #231f20;
}
.coffee-medium__arm::before {
  content: "";
  width: 15px;
  height: 5px;
  position: absolute;
  top: 7px;
  left: -15px;
  background-color: #9e9495;
}
.coffee-medium__cup {
  width: 80px;
  height: 47px;
  position: absolute;
  bottom: 0;
  left: calc(50% - 40px);
  background-color: #FFF;
  border-radius: 0 0 70px 70px / 0 0 110px 110px;
}
.coffee-medium__cup::after {
  content: "";
  width: 20px;
  height: 20px;
  position: absolute;
  top: 6px;
  right: -13px;
  border: 5px solid #FFF;
  border-radius: 50%;
}
@keyframes liquid {
  0% {
    height: 0px;  
    opacity: 1;
  }
  5% {
    height: 0px;  
    opacity: 1;
  }
  20% {
    height: 62px;  
    opacity: 1;
  }
  95% {
    height: 62px;
    opacity: 1;
  }
  100% {
    height: 62px;
    opacity: 0;
  }
}
.coffee-medium__liquid {
  width: 6px;
  height: 63px;
  opacity: 0;
  position: absolute;
  top: 50px;
  left: calc(50% - 3px);
  background-color: #74372b;
  animation: liquid 4s 4s linear infinite;
}
.coffee-medium__smoke {
  width: 8px;
  height: 20px;
  position: absolute;  
  border-radius: 5px;
  background-color: #b3aeae;
}
@keyframes smokeOne {
  0% {
    bottom: 20px;
    opacity: 0;
  }
  40% {
    bottom: 50px;
    opacity: .5;
  }
  80% {
    bottom: 80px;
    opacity: .3;
  }
  100% {
    bottom: 80px;
    opacity: 0;
  }
}
@keyframes smokeTwo {
  0% {
    bottom: 40px;
    opacity: 0;
  }
  40% {
    bottom: 70px;
    opacity: .5;
  }
  80% {
    bottom: 80px;
    opacity: .3;
  }
  100% {
    bottom: 80px;
    opacity: 0;
  }
}
.coffee-medium__smoke-one {
  opacity: 0;
  bottom: 50px;
  left: 102px;
  animation: smokeOne 3s 4s linear infinite;
}
.coffee-medium__smoke-two {
  opacity: 0;
  bottom: 70px;
  left: 118px;
  animation: smokeTwo 3s 5s linear infinite;
}
.coffee-medium__smoke-three {
  opacity: 0;
  bottom: 65px;
  right: 118px;
  animation: smokeTwo 3s 6s linear infinite;
}
.coffee-medium__smoke-for {
  opacity: 0;
  bottom: 50px;
  right: 102px;
  animation: smokeOne 3s 5s linear infinite;
}
.coffee-footer {
  width: 95%;
  height: 15px;
  position: absolute;
  bottom: 25px;
  left: calc(50% - 47.5%);
  background-color: #41bdad;
  border-radius: 10px;
}
.coffee-footer::after {
  content: "";
  width: 106%;
  height: 26px;
  position: absolute;
  bottom: -25px;
  left: -8px;
  background-color: #000;
}
.author {
    font-style: italic;
    text-align: right;
    color: grey;
    font-size: 0.6rem;
    font-family: serif;
}
</style>



<div class="wrapper">
  <div class="container">
    <div class="coffee-header">
      <div class="coffee-header__buttons coffee-header__button-one"></div>
      <div class="coffee-header__buttons coffee-header__button-two"></div>
      <div class="coffee-header__display"></div>
      <div class="coffee-header__details"></div>
    </div>
    <div class="coffee-medium">
      <div class="coffe-medium__exit"></div>
      <div class="coffee-medium__arm"></div>
      <div class="coffee-medium__liquid"></div>
      <div class="coffee-medium__smoke coffee-medium__smoke-one"></div>
      <div class="coffee-medium__smoke coffee-medium__smoke-two"></div>
      <div class="coffee-medium__smoke coffee-medium__smoke-three"></div>
      <div class="coffee-medium__smoke coffee-medium__smoke-for"></div>
      <div class="coffee-medium__cup"></div>
    </div>
    <div class="coffee-footer"></div>
  </div>
</div>
<div class="author">
Author: Henrique Rodrigues (August 31, 2018)
</div>