How to write Markdown and prepare your environment (with VSCode)

Hello,
I'm Mandai, the Wild Team member of the development team.

Many people are familiar with the document format known as Markdown, and many of you use it regularly.
In this article, I would like to summarize the bare minimum of how to write Markdown, as well as some tips for writing more strict and beautiful Markdown, in order to help spread its use more widely within your company.

Benefits of using Markdown

First, let's consider the benefits of using Markdown

The benefits of using Markdown are immeasurable, especially in technical fields.
Markdown has a strict format, which gives it the following advantages:

1. The sentence structure is simple, making it easy to convert to other formats
2. Documents can be simplified with simple symbols and rules, allowing you to focus on document refinement
3. You can embed source code in Markdown documents (but you can't execute it). This makes it easy to create a structure consisting of a sentence and a section of code that complements it, especially in technical fields
4. Since it is simply a document format, you can write text without relying on a specific editor

When writing documents for the Beyond Blog I use Markdown (this article is no exception).
After writing, I revise and proofread it, then convert it to HTML, attach images, and make fine adjustments to the layout.

The conversion process is handled using gulp, and a Node.js module allows for one-shot conversion.
In my case, due to CSS restrictions, the HTML output from the module cannot be used as is, so I run it through my own converter before converting it with the module.
In this way, I can say that I am making the most of the fact that the sentence structure is simple, making it easy to process and allowing me to focus on revision.

Also, since the articles written on Beyond Blog are generally technical, it is very helpful to be able to write source code within the article

 

Let's get started!

First, let's start writing Markdown.
When writing an essay, the title is written on the far right, right?

So, let's learn how to write a title

# It's a little late, but let's summarize Markdown

 

That's it.
This article I'm currently writing is the same as the one I'm using Markdown for.
When you title a document in Word, you have to decide whether to center the title or how many margins to add, but with Markdown, you can be free from all those worries.

Once you've written the title, the next step is to write the content.
Let's write it like this!

# It's a little late, but I'll summarize Markdown. Hello. I'm Mandai, the Wild Team member of the development team. I'm sure many of you are familiar with the document format known as Markdown, and many of you use it regularly

 

After the title, insert a line break and then start writing your text

Do you think you're starting to get the general idea of ​​how it works?
Now all you have to do is scribble down whatever comes to mind!

 

I want to write a list with bullets at the beginning of the lines

You can think of a list as being the ul tag in HTML

Defining an unordered list is very easy:

Just put "-", "+", or "*" at the beginning of the line and then enter one half-width space

- It's easy to write a list in Markdown. - For example, just type "-" and a space at the beginning of a line like this. - You can also nest lists by simply typing a space or tab at the beginning of a line. - It's very easy

 

There are two things to be careful about:

• Do not put line breaks between lists
• There are various dialects regarding the number of spaces (or tabs) used when nesting

That's all

Different editors recognize spaces when nesting.
We'll discuss this dialect later, but for now, just know that it exists.
Your editor should be able to adjust it to match web services where you might post Markdown, such as github or backlog.

 

I want to write a numbered list

The functionality described in this section corresponds to the ol tag in HTML

The ordered list mentioned in
the section on the benefits of using Markdown The Markdown version of this section is shown below.

1. The sentence structure is simple, so it is easy to convert to other formats. 1. Documents can be simplified with simple symbols and rules, so you can focus on refining the document. 1. Source code can be embedded within a Markdown document (although it cannot be executed). Especially in technical fields, it is easy to create a structure consisting of sentences and complementary code sections. 1. Because it is simply a document format, you can write sentences without relying on a specific editor

 

When the string "1." appears, it signals the beginning of a numbered list.
Even if consecutive numbers follow, the string should start with "1."
There is no problem with the specifications if the 1 counts up, but if it does, the numbers will need to be rewritten if the order is changed, which requires more maintenance work.

Here too, there are only two things to be careful about: not putting line breaks between lists, and the number of spaces when nesting

Displaying an HTML list requires wrapping it in li tags, so Markdown is easier to write

 

I want to write a headline

When the amount of text becomes large, you will need to write it in chapters

It's also very easy to add headings to each item, just write it like this:

# This is the main item (title). Write the opening here. ## This is the middle item. Write about the middle item here. ### This is the small item. Write about the small item here

 

By increasing the number of "#" symbols, you can define smaller items, making it easier to write clear sentences

 

I want to define a link

Of course, there are times when you want to include a link to an article on the Internet in your text

In such cases, you can easily write using Markdown

This is a link to [Beyond's corporate website](https://beyondjapan.com)

 

Enter the string you want to make into a link between "[]", then enter the URL of the link destination between "()".
It's easy to understand because it's used like the HTML a tag.

 

I want to write source code

Markdown has something similar to the code tag in HTML
, called a fenced code block.

php<?php class hogehoge { function echo($message) { echo $message; } } $a = new hogehoge(); $a-> echo();

 

This code has no real value, but when you write source code in Markdown, the line following the three "`" characters and up to the next three "`" characters will be recognized as source code. The "
php" written after the first "`" is the programming language of the source code and is not required.

You can also nest them by adjusting the number of pieces

You can use the ~ (tilde) as an alternative to `, but you cannot mix them

In Markdown, the boundary of a fenced code block is originally defined as four spaces, not backticks or tildes. However, it is not well known and may not appear to be anything at first glance, and some viewers do not respond to it. Therefore, if you remember this as trivia, you may have occasion to show it off

 

I want to define a table

Visually, I think the most flashy item is the table

The way to write it is in the following format:

Column A | Column B | Column C ---------|----------|--------- A1 | B1 | C1 A2 | B2 | C2 A3 | B3 | C3

 

At first glance, it looks a bit like a table, but the viewer formats it nicely depending on the number of "|"s, which is very convenient.
Because the elements are lined up horizontally, it's very convenient to swap them row by row, which is a big plus.

The "---------|----------|---------" part separates the header and data parts, but some sites, such as github, require three or more hyphens.
In VSCode, the viewer will respond even if there is only one hyphen.

Generally, the editor will interpret the information flexibly, but it's a good idea to input around three items as a guideline

 

Define text emphasis

If you want to highlight text, surround it with "__" and it will be highlighted

In Markdown, this is how you __emphasize__

 

Pay attention to the placement of the spaces:
start with one space and two underscores, and
end with two underscores and one space.

There is also an alternative character "**".
There is no difference in the Markdown definition between the two.

 

About dialects

There were several expressions throughout the text that hinted (or directly stated) that Markdown has dialects

For example, I think the most famous Markdown extension GitHub Flavored Markdown , but there are also many other extension dialects such as R Markdown, Maruku, and PHP Markdown Extra.

GitHub Flavored Markdown disables underscore highlighting, and the viewer converts URLs in text into links. The use of emojis is also not included in the Markdown specification

R Markdown has a key feature that allows you to write R syntax as source code and have the parser execute it as R

PHP Markdown Extra seems to place emphasis on converting to HTML, allowing you to assign things like IDs and classes, and the parser works with an HTML-like approach, such as in cases where HTML and Markdown are mixed, and with block elements and inline elements

Also, the original Markdown, which is the source of the code, is specifically called CommonMark, but I don't think that's the scope of the test.
CommonMark has very detailed test cases in HTML, so even though it's in English, just reading the page gives you a lot of insights.

CommonMark Spec (This article uses 0.28 as a reference)

 

Writing Markdown in Visual Studio Code

There is a useful extension for writing Markdown in Visual Studio Code (hereafter referred to as VSCode), so I will introduce it at the end.By
the way, when you write Markdown in VSCode, it comes with a useful feature by default that thoroughly highlights programming language within fenced code blocks.

 

Markdown All in One

As the name suggests, this extension provides all the functionality you need for Markdown.
With this extension installed, you can write Markdown comfortably.

In my case, I often write down my ideas in bullet points and then format them accordingly, so the features that eliminate unnecessary keyboard operations are fantastic, such as the ability to complete the list with the Enter key, or to add a tab to the beginning of a line when pressing the Tab key on a list to create a sublist

Markdown All in One - Visual Studio Marketplace

 

Markdown Preview Mermaid Support

This extension renders the mermaid library in the Markdown preview.
mermaid is a library for displaying flowcharts, sequence diagrams, and Gantt charts. Although you will need to learn the mermaid syntax separately, this extension will definitely help you create documents more efficiently by allowing you to write diagrams using only Markdown.

Markdown Preview Mermaid Support - Visual Studio Marketplace

 

markdownlint

In fact, it can be quite difficult to get started, but it's like a Markdown training cast.
It requires very strict Markdown syntax, and if you make an error, you'll get an immediate warning.

When I first started using it, I remember it being nothing but painful, but now it has corrected my condition so well that I have almost forgotten it even existed

I think it's no exaggeration to say that my MD skills have improved significantly since I discovered this extension

At least I've improved enough to be able to write an article like this

markdownlint - Visual Studio Marketplace

 

summary

Markdown itself starts out as a language that can be converted to HTML, so this explanation has been limited to explaining what it looks like when converted to HTML. What do you think?
In fact, there are many more ways to express things in Markdown, but this time we've focused on the basic notation.

Although I only covered VSCode, I'm happy that I was able to introduce some helpful tools that make writing Markdown easier.
I hope you will use markdownlint in moderation.

It would be counterproductive if it was so difficult that I ended up hating Markdown

Once your MD skills improve, I think it will be useful in situations where speed is required, such as taking minutes of meetings, and well-written Markdown can even be purely beautiful (this is the height of putting the cart before the horse...!!)

That's all