Markdown
I love Markdown, it’s great. Let’s talk about it for a bit. I’ll go through the who, what and how, then I’ll show you my own flavor. Yes, I have my own flavor of Markdown, as do many other people.
Note that this article is ported from the previous version of this website, which used a different system, custom attributes will not display correctly
Simplicity and Innovation Go Hand in Hand …
MD (Markdown) is usable by anyone, it’s the perfect communist language ☭. The syntax is very simple, in my opinion intuitive and really, really easy to memorize. As a developer, I appreciate its extensibility too. It can be combined with HTML for additional utility (not everywhere though.)
The basic gist of it is being able to write an easily convertible text. You might stop me on the street and ask, ‘Convertible to what, Martin?’ After getting over the fact that a total stranger knows my name and asked me a very strange question randomly, I’d reply, ‘XHTML, stranger.’ Yes, Markdown’s primary function was originally for conversion into XHTML (Extensible HyperText Markup Language, it’s a more strict version of HTML - case sensitive, uses XML parsers, etc.
Nowadays it’s used both for conversion and regular writing. You can run into MD on GitHub, GitLab (README.md, anyone?), StackOverflow, Reddit and many other text editors (unfortunately not Google Docs, but there are some Add-ons for that, I think). Have you ever seen **this** turning into this? That’s MD too (Discord chat, Facebook, …)
In fact, the editor I’m writing this in, the very parser that parses this page before displaying it - Markdown. It’s simple, so it’s not distracting, but still allows you to format your text. This makes it ideal for writers - there’s nothing worse than lowering the quality of your text through pointless distractions.
Now That You See … Let’s Check the Syntax!
# Headings use the number signs / hashes
## Smaller heading, these go up to six levels deep
Some people use either ==== or ---- (any number of them) for their headings, like this
--------------------------------------------------
Paragraphs can be separated by a line break,
This second line would still be a part of the first paragraph, it wouldn't appear on a new line.
Line breaks look like this, another paragraph, however, adding two spaces to the end of a line and leaving no line breaks in between the lines⌴⌴
allow you to create a new line, it's basically a line break <br>⌴⌴
You can decorate your text with *Italic*, **bold** or ***both!***, you don't need to use the asterisks, you can use _*underscores*_. I prefer asterisks...
--------
^ a bunch of dashes, asterisks or underscores (at least 3) make a horizontal rule, that's a line that separates text horizontally.
You can add images:
[Links look very similar, they just don't have exclamation mark in front of their brackets. This bit would show up as the text of your link](www.toms.click)
> If you wanted to quote this, you'd use a blockquote, which can be single or multi-line
>
>multi-paragraph
>
>> or even a quote within another quote!
You can make lists starting with asterisks, dashes or numbers, that's gonna give you an ordered or an unordered list.
Every programmer will appreciate the \`inline code\` or even block code
\`\`\`language
And finally, you can escape any characters with a \
\`\`\`
My Own Flavor
Note that this article is ported from the previous version of this website, which used a different system, custom attributes will not display correctly
I added a bunch of tags/traits, which I use in most of my apps. They’re mostly decorative and you probably saw a few of them already.
Let’s Start With the Boring Ones:
As Markdown doesn’t contain subscript or superscript, I added that: 2u(2), 2v(n), 2v(k)u(2). Many of my Czech math articles use these, along with the Sum trait, which I recently broke, haha: s{toSum}(top)(bottom).
I kinda wanted some smaller text. This tag, which is just a 7( and the same on the other side was created for that.
Modifying the inline code to also take language as a parameter (the first word before a space), that’s for the syntax highlighting: SELECT * FROM something;.
The Fun Ones
Fractions! /{top}{bottom}. Text above another text! ^[bottom](top). Special tables, that’s more of a style thing, but still:
|Dv(1)|Dv(2)|Dv(3)|Dv(D)|Supply
:-----:|:-----:|:-----:|:-----:|:-----:|:-----:
Sv(1)|✗u(6)|120u(3)|10u(5)|90u(0)|0
Sv(2)|✗u(5)|✗u(9)|150u(2)|✗u(0)|0
Sv(3)|70u(5)|✗u(7)|**10**u(8)|✗u(0)|**0**
Demand|0|0|**0**|0|
| Dv(1) | Dv(2) | Dv(3) | Dv(D) | Supply | |
|---|---|---|---|---|---|
| Sv(1) | ✗u(6) | 120u(3) | 10u(5) | 90u(0) | 0 |
| Sv(2) | ✗u(5) | ✗u(9) | 150u(2) | ✗u(0) | 0 |
| Sv(3) | 70u(5) | ✗u(7) | 10u(8) | ✗u(0) | 0 |
| Demand | 0 | 0 | 0 | 0 |
Finally, I added these today:
Definitions: (:term|definition:)
Abbreviations: [:abbr|definition:]
Colors: {:indigo|This should be indigo!:}
Which Parser Do I Use for toms.click, How Does It Work?
Cebe’s markdown. It’s really easy to use (install through Composer) and extend (it’s simple and pretty well documented), this is an example of the text above text (note, to include this in the parser, you need to actually include it in the main Markdown class using the use keyword, like this: use inline\_RubyTrait;.):
/**
* @copyright Copyright (c) 2019 Martin Toms
*/
namespace cebe\markdown\inline;
/**
* Adds a ruby inline elements
*/
trait _RubyTrait
{
/**
* syntax: ^[bottom](top)
* as: <ruby>bottom<rt>top</rt></ruby>
*
* @marker ^[
*/
protected function parseRuby($markdown)
{
// check whether the marker really represents a strikethrough (i.e. there is a closing ~~)
if (preg_match('/\^\[(.*?)\]\((.*?)\)/', $markdown, $matches)) {
return [
// return the parsed tag as an element of the abstract syntax tree and call parseInline() to allow
// other inline markdown elements inside this tag
['ruby', $this->parseInline($matches[1]), $this->parseInline($matches[2])],
// return the offset of the parsed text
strlen($matches[0])
];
}
// in case we did not find a closing ~~ we just return the marker and skip 2 characters
return [['text', '^['], 2];
}
protected function renderRuby($element)
{
return '<ruby>' . $this->renderAbsy($element[1]) . '<rt> ('.$this->renderAbsy($element[2]).') </rt></ruby>';
}
abstract protected function parseInline($text);
abstract protected function renderAbsy($blocks);
}
The trait looks for the match using the PHPDoc /** @marker */ and parse method, through regex. It then returns the results and renders it. That’s it!
Summary
Markdown is great. The syntax is simple and easy to learn. It’s not distracting. It’s great.