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

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

Many of you are probably familiar with the Markdown document format, and many use it regularly.
This time, in order to further promote Markdown adoption within your company, I'd like to summarize the essential writing style and some points for writing more strict and elegant Markdown documents.

Benefits of using Markdown

First, let's consider the benefits of using Markdown

The advantages of using Markdown, especially in technical fields, are immeasurable.
Because Markdown has a well-defined format, it offers the following benefits:

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

I write my Beyond Blog documents in Markdown (this article is no exception).
After writing, I revise and proofread, then convert it to HTML, add images, and make minor layout adjustments.

The conversion process is handled by gulp, allowing for one-click conversion using a Node.js module.
In my case, due to CSS constraints, the HTML output by the module cannot be used directly, so I use my own converter before converting it with the module.
In this way, I am making the most of the advantages of having a simple document structure, which makes it easy to process and allows 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!

Let's start by writing in Markdown.
When you write 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 all there is to it.
This article I'm writing right now is the same as it was in Markdown.
When you title a document in Word, you have to worry each time about whether to center the title, how many characters to add as a margin, etc., but with Markdown, you're instantly freed 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

Are you starting to get the general idea?
Now all you have to do is scribble down your thoughts and feelings!

 

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

The way nested spaces are handled varies depending on the editor.
We'll discuss these dialects later, but for now, just be aware that they exist.
Editors should allow for adjustments, so you can customize them 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 section on the advantages of using Markdown,The use of numbered lists, which was mentioned in
The Markdown version of this section is as follows:

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

 

The appearance of the string "1." signals the start of a numbered list.
Even if consecutive numbers follow, the string will always begin with "1.". While
it would technically be acceptable for the 1 to count up, doing so would require rewriting the numbers if the order of the entries changes, increasing maintenance effort.

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 text you want to make into a link inside the square brackets "[]", followed by the URL of the link destination inside the parentheses ()". It's
similar to using 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, it's called a fenced code block.

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

 

This code has no practical use, but when you want to write source code in Markdown, the line after three backticks (`) up to the next three backticks (`) is recognized as source code. The
`php` written after the first backtick 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

 

It looks somewhat like a table, but the viewer neatly adjusts the formatting according to the number of "|" symbols, making it very convenient. The
fact that the elements are arranged in a single horizontal row makes rearranging them row by row extremely easy, which is a big plus.

The part "---------|----------|---------" separates the header and data sections, but GitHub and similar platforms require three or more hyphens.
VS Code's viewer will respond even with just one.

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 spaces.
Start with one space and two underscores.
End with two underscores and one space.

There is also the alternative character "**".
There is no difference in 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, the most famous extension for Markdown is GitHub Flavored Markdown, but there are 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 that served as the source material is specifically called CommonMark, but I don't think that's within the scope of the test.
Regarding CommonMark, there are quite detailed test cases written in HTML, so even though the page is in English, you can gain a lot of insights just by reading it.

CommonMark Spec (This article uses version 0.28 as a reference)

 

Writing Markdown in Visual Studio Code

Finally, I'd like to introduce a useful extension for writing Markdown in Visual Studio Code (VSCode).
Incidentally, VSCode has a built-in feature that, while perhaps not very useful, provides proper highlighting for programming languages ​​within fenced code blocks when you write Markdown.

 

Markdown All in One

As the name suggests, this extension provides all the necessary Markdown features in one package.
With this installed, you can generally 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 is an extension that 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 speed up your document creation process by allowing you to create diagrams using only Markdown.

Markdown Preview Mermaid Support - Visual Studio Marketplace

 

markdownlint

Rather, while you might struggle at first when you adopt it, it's like a Markdown training brace.
It demands fairly strict Markdown syntax, and if you make a mistake, a warning will be displayed immediately.

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

Since Markdown itself is based on expressions that can be converted to HTML, the explanation ended up being something like, "This is what it looks like when converted to HTML." What did you think?
Actually, there are many more ways to express things in Markdown, but this time we focused on the basic notation.

Although I've only covered VSCode, I'm satisfied with this post because I was able to introduce some helpful tools that make writing Markdown easier.
Please use markdownlint responsibly and within reasonable limits.

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