How to write Markdown & environment preparation (with VSCode)

Hello.
I'm Mandai, in charge of Wild on the development team.

I think many people are familiar with the document format called Markdown, and many of them use it regularly.
This time, in order to spread Markdown further within the company, I would like to summarize the minimum necessary writing methods and points for writing more strict and beautiful Markdown.

Advantages of using Markdown

First, let's consider the advantages of using Markdown.

The benefits of using Markdown, especially in the technical field, are immeasurable.
Markdown has the following advantages because it has a neat format.

1. Simple sentence structure makes 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. It is possible to embed source code within a Markdown document (although it is not executable). Especially in the technical field, it is easy to create a structure consisting of a sentence and a code part that complements it.
4. Since it is a simple document format, you can write without relying on a specific editor.

I write documents in Beyond Blog using Markdown (this article is no exception).
After writing, editing and proofreading, converting to HTML, attaching images, and fine-tuning the layout.

The conversion is handled using gulp, and one-shot conversion is possible using a Node.js module.
In my case, due to CSS restrictions, I cannot use the HTML output from her module as is, so I run it through my own converter and then convert it using the module.
In this way, it can be said that the simple structure of the text makes it easy to edit and makes the most of the focus on elaboration.

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

 

Let's get started!

Let's start writing Markdown.
When writing an essay, the title is the first thing you write on the right.

So let's learn how to write titles.

# It's late, but I'll summarize Markdown.

 

That's all.
This article I'm currently writing is the same when he uses Markdown.
When creating a title for a document in Word, you have to worry about whether to center the title or how many characters to include in the margin, but with Markdown, you can be freed from such worries.

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

# It's late, but I'd like to summarize about Markdown Hello. I'm Mandai, in charge of Wild on the development team. I think many people are familiar with the document format called Markdown, and many of them use it regularly.

 

After the title, insert a line break and start writing.

Do you understand the flow somehow?
After that, all you have to do is write as you please!

 

I want to write a list with a central black character at the beginning of the line.

It is OK to understand that a list is a ul tag in HTML tags.

Defining an unordered list is very easy.

Place either "-", "+", or "*" at the beginning of the line and enter one half-width space. That's it.

- Writing a list in Markdown is easy - For example, just enter "-" and a half-width space at the beginning of a line like this - You can also nest lists by just inserting a space or tab at the beginning of a line - It's very easy, isn't it?

 

There are two things to be careful of.

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

That's all.

Spaces when nesting are recognized differently depending on the editor.
I will discuss this dialect later, but for now, it's enough to say that such a dialect exists.
The editor should be able to adjust it to suit any web service you might post Markdown to, such as github or backlog.

 

I want to write a numbered list

The functions described in this article correspond to the ol tag in HTML.

It is also easy to use ordered lists, which were introduced in
the section on the benefits of using Markdown The Markdown version of this part is as follows.

1. Simple sentence structure makes it easy to convert to other formats 1. Documents can be simplified with simple symbols and rules, allowing you to focus on document refinement 1. Source code can be stored in Markdown documents Can be embedded (but not executed). Especially in the technical field, it is easy to create a structure consisting of a text and a code part that complements it. 1. Because it is a simple document format, you can write text without depending on a specific editor.

 

When the string "1." appears, it signals the beginning of a numbered list.
Even if there are consecutive numbers, the beginning of the string should be "1.".
There is no problem with the specifications even if 1 is counted up, but if the order is changed when the number is counted up, it is necessary to rewrite the numbers, which requires maintenance.

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

HTML list display needs to be wrapped in a li tag, so Markdown is easier to write.

 

I want to write a headline

When the amount of text increases to a certain extent, you will need to write the text in chapters.

It is very easy to add a heading to each item, as shown below.

# Main item (title) Write the beginning here ## Medium item Write about the medium item here ### Small item Write about the small item here

 

By increasing the number of "#" characters, you can define smaller items, which makes it easier to write sentences with good visibility.

 

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.

Even in such cases, you can easily write in Markdown.

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

 

Enter the character string you want to make into a link in "[]", then enter the URL of the link destination in "()".
Its usage is similar to the HTML a tag, so it should be easy to understand.

 

I want to write source code

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

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

 

Although it is a code that has no value, when you want to write source code in Markdown, the line from the next line with three ```'' characters to the line with three ```'' characters again is recognized as source code. .
The word "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.

You can also use ~ (tilde) as an alternative character for `, but you cannot mix them.

Note that Markdown originally defines the border of a fenced code block as four spaces, not backquotes or tildes, but at first glance it looks like there is no border, and some viewers may not be aware of this. So, if you memorize it at least, there will be situations where you can stand out.

 

I want to define a table

I think the most showy part of the painting is the table.

The way to write it is as follows.

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

 

Although it looks like a table, it is very convenient because the viewer adjusts the appearance according to the number of "|" characters.
The key point is that since the elements are lined up horizontally, it is very convenient to swap rows.

The part "---------|----------|---------" separates the header part and the data part, but in github etc. must have three or more hyphens.
In VSCode, the viewer will respond even if there is only one.

Basically, the editor will interpret it more flexibly, but I think it's best to enter about 3 as a guideline.

 

I want to define character emphasis

If you want to emphasize a character, surround it with "__" and it will be highlighted.

In Markdown, we do __emphasis__ like this:

 

Pay attention to the location of the spaces.
Start with a space and two underscores.
When finished, end with two underscores and one space.

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

 

About dialects

Several times in the text, there were expressions that suggested (or even clearly) that Markdown has dialects.

I think the most famous Markdown extension GitHub Flavored Markdown

GitHub Flavored Markdown has things like disabling underscore highlighting and having the viewer convert URLs in text to links. The use of emojis is actually not included in the Markdown specification.

R Markdown has the feature that when R syntax is written as source code, the parser executes it as R.

PHP Markdown Extra seems to place emphasis on conversion to HTML, allowing things like ID and class to be added, cases where HTML and Markdown are mixed, and HTML-oriented ideas such as block elements and inline elements. The parser is now working.

Also, the original Markdown that became the origin is especially called CommonMark, but I feel that that is not the scope of the test.
As for CommonMark, the test cases are quite detailed and are converted into HTML, so even though the page is in English, I noticed a lot of things just by reading it.

CommonMark Spec (0.28 is referenced in this article)

 

When writing Markdown with Visual Studio Code

There are extensions that are useful when writing Markdown in Visual Studio Code (hereinafter referred to as VSCode), so I will introduce them at the end.
By the way, when you write Markdown with VSCode, it comes with a nice feature by default that allows you to clearly highlight programming languages ​​in fenced code blocks.

 

Markdown All in One

As the name suggests, it is an extension that has all the necessary functions for Markdown.
Once you have this in place, you can generally write Markdown comfortably.

Especially in my case, I often format my ideas after making them into bullet points in a list, so I can use the enter key to complete the list, or press the tab key on a list to create a sublist. The function that saves unnecessary keyboard operations by adding `` to the beginning of the line is amazing.

Markdown All in One - Visual Studio Marketplace

 

Markdown Preview Mermaid Support

This is an extension for rendering a library called mermaid with Markdown preview.
mermaid is a library for displaying flowcharts, sequence diagrams, and Gantt charts. Although you need to separately memorize the mermaid notation, it is an extension that will definitely help you create materials because you will be able to draw diagrams using only Markdown.

Markdown Preview Mermaid Support - Visual Studio Marketplace

 

markdownlint

Rather, it is like a Markdown training cast, although it is often difficult at first to introduce it.
A fairly strict Markdown notation is required, and if you make an incorrect description, you will receive an immediate warning.

I remember when it was first introduced that it was nothing but a pain, but now it has been corrected so well that I have even forgotten it existed.

I don't think it's an exaggeration to say that my MD skills have improved considerably since I discovered this extension.

At least I've improved enough to write articles like this.

markdownlint - Visual Studio Marketplace

 

summary

Since Markdown itself is an expression that can be converted to HTML, the explanation ended up being something like, ``This is what happens when you convert to HTML.'' What do you think?
Actually, there are many more expressions in Markdown, but this time he focused on the basic notation.

Although I only used VSCode, I was also able to introduce some helpful tools that will make it easier to write Markdown, so I'm satisfied with this article.
Please use markdownlint according to the usage instructions.

If you end up hating Markdown because it's too difficult, you're missing the point.

Once you improve your MD skills, I think you will be able to demonstrate your power in situations where speed is required, such as meeting minutes, and I feel that a well-finished Markdown is pure beauty (this is the ultimate way to put the cart before the horse...) .!!).

That's it.