本記事ではdev.toでの記事の投稿方法や
記事の編集スタイルであるMarkdownの簡単な説明を行います。
dev.toのアカウントをお持ちでない方はこちらの記事を参考に
https://dev.to/programmingmonky/devto--25lm
まずはdev.toのアカウントを作成してください。
記事の作成方法について
記事の作成画面に遷移するには、
画面上部のメニューバーの「WRITE A POST」ボタンをクリックします。
記事の投稿画面の解説
「WRITE A POST」ボタンを押すと、記事の作成画面が表示されたと思います。
この画面の使い方について解説します
上部UI部分
- 1.
[HELP]ボタン:dev.toの説明記事が表示されます(英語)。 - 2.
[MARKDOWN]ボタン:記事の編集画面が表示されます。 - 3.
[PREVIEW]ボタン:記事のプレビュー画面が表示されます。- 編集したmarkdownが正しく描画されるかをこの画面で確認できます。
- 4.
[SAVEPOST]ボタン:記事の投稿内容を一時保存します。 - 5.
[Upload Image]ボタン:画像のアップロードに利用します。- ボタンを押してアップロードする画像をエクスプローラで選択します。
- 画像をアップロードするとボタンの右にuploadされた画像のURLが出現します。
- 画像をアップロードするとボタンの右にuploadされた画像のURLが出現します。
- 記事の中に画像を埋め込む方法は後述のmarkdownの解説で行います。
- ボタンを押してアップロードする画像をエクスプローラで選択します。
下部の記事部分
- 1記事のヘッダとなる部分です。
- タイトル、タグなどの記事のメタ情報をここに書きます。
- 2記事本体の部分です。ここにmarkdownで記事を書きます
記事ヘッダの解説
記事ヘッダは初期値として以下のようになっていると思います。
---
title: ""
published: false
description:
tags:
---
それぞれの行は記事の情報を表しています。
各行の意味を説明します。
- title:記事のタイトルを設定します
- published:公開非公開を設定します。
-
trueを設定すると記事を公開できます。 -
falseを設定すると記事は非公開になります。- 初期値は
falseです。 - 非公開でもリンクを共有することで知人などに限定公開できます。
- 初期値は
-
-
description: 記事の概要を書きます。
- 記事中には出ませんが、twitterやslackにリンクした時のカードに記載されます。
- Slackに張った例です。赤枠の部分がdescriptionに書いた内容です。
tags:その記事のジャンルをcsvで記載します。最大4つまで記載できます。
実例としてこの記事のヘッダを以下に示します。
文法のmarkdownについて
dev.toではmarkdownを利用して投稿記事を作成します。
まずはmarkdownに関して簡単に説明いたします。
正確な定義はWikipedia等をご参照ください。
初心者の方にざっくり説明すると
- pandocやjekyllなどのツールを使ってihtmlやpdfに変換できるシンプルなテキストの形式
- いろいろな場所で利用されており、流行っています。
- 私が知っているだけでも以下のものがあります。
- GitHubのreadme.md(ソースコードの概要を示すドキュメント)
- Redmineのテキスト装飾
- Kotlinのドキュメンテーション(Kdoc)
- はてなブログやQiitaの投稿
- つまり、初めてmarkdownを覚える人でも、別のところでmarkdownを使う機会が来る可能性が高いです。
- 今dev.toのためにmarkdownを勉強すると後々役に立つと思いますよ。
- 私が知っているだけでも以下のものがあります。
- このような入れ子になった箇条書きをうまく表現、変換することができます。
- Excel方眼紙やhtmlを手書きする場合と比べて少ない労力で編集記述することができます。
- htmlなどの一般的なマークアップ言語に比べてレンダリング前の可読性がとても良いです。
- いろいろな場所で利用されており、流行っています。
さっそくmarkdownとhtmlを比較してみましょう。まずはマークダウンです。
# 見出し1
先頭をシャープ記号の行は見出しの行になります。
htmlでいうところのh1タグです。シャープを重ねることで
h2,h3相当のタグを作って入れ子にすることができます。
## 見出し2
リンクのサンプルです。[Googleのトップページです](https://www.google.co.jp/)
[]内の文字が画面に青く表示したいテキストを書きます。()の中にリンク先のURLを書きます。
表のサンプルです。htmlのように複雑なタグを利用する必要はありません。
| id | type | usage content | amount |
|----|-------------------|----------------|-----------|
| 1 | snack | banana | 100 yen |
| 2 | Writing utensils | pencils | 200 yen |
| 3 | sporting goods | soccer ball | 3000 yen |
| 4 | Gifts | game software | 4000 yen |
| 5 | Consumables | water | 100 yen |
markdownの構文を覚えるのが面倒な方は、
[こちらのサイト](https://donatstudios.com/CsvToMarkdownTable)で
csvやtsvの形式から簡単にmarkdownの票に変換することができます。
tsvが使えるのでexcelからもコピペで簡単にこの形式に変換できますよ。
### 見出し3
- 箇条書きのサンプルです
- 入れ子にすることができます。
- 同じレベルで並べることもできます
- 特に入れ子にできる件数に制限はないと思います。
- 読みにくくなるので入れ子は3段程度にとどめておくのがよいでしょう。
# 引用について
引用のサンプルです。
大なり記号>を使うことで引用になります。
>あなたのぶどう畑の実を取りつくしてはならない。
>またあなたのぶどう畑に落ちた実を拾ってはならない。
>貧しい者と寄留者とのために、これを残しておかなければならない。
>わたしはあなたがたの神、主である。
>レビ記 19:10
メールなどで返信した時の形式とよく似ています。
plane textの状態でも読みやすいですね！
htmlだとこうなります。
<h1 id="-1">見出し1</h1>
<p>先頭をシャープ記号の行は見出しの行になります。
htmlでいうところのh1タグです。シャープを重ねることで
h2,h3相当のタグを作って入れ子にすることができます。
</p>
<h2 id="-2">見出し2</h2>
<p>リンクのサンプルです。<a href="https://www.google.co.jp/">Googleのトップページです</a></p>
<p>[]内の文字が画面に青く表示したいテキストを書きます。()の中にリンク先のURLを書きます。</p>
<p>表のサンプルです。htmlのように複雑なタグを利用する必要はありません。</p>
<table>
<thead>
<tr>
<th>id</th>
<th>type</th>
<th>usage content</th>
<th>amount</th>
</tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td>snack</td>
<td>banana</td>
<td>100 yen</td>
</tr>
<tr>
<td>2</td>
<td>Writing utensils</td>
<td>pencils</td>
<td>200 yen</td>
</tr>
<tr>
<td>3</td>
<td>sporting goods</td>
<td>soccer ball</td>
<td>3000 yen</td>
</tr>
<tr>
<td>4</td>
<td>Gifts</td>
<td>game software</td>
<td>4000 yen</td>
</tr>
<tr>
<td>5</td>
<td>Consumables</td>
<td>water</td>
<td>100 yen</td>
</tr>
</tbody>
</table>
<p>markdownの構文を覚えるのが面倒な方は、
<a href="https://donatstudios.com/CsvToMarkdownTable">こちらのサイト</a>で
csvやtsvの形式から簡単にmarkdownの票に変換することができます。
</p>
<p>tsvが使えるのでexcelからもコピペで簡単にこの形式に変換できますよ。</p>
<h3 id="-3">見出し3</h3>
<ul>
<li>
箇条書きのサンプルです
<ul>
<li>入れ子にすることができます。</li>
<li>同じレベルで並べることもできます</li>
</ul>
</li>
<li>特に入れ子にできる件数に制限はないと思います。</li>
<li>読みにくくなるので入れ子は3段程度にとどめておくのがよいでしょう。</li>
</ul>
<h1 id="-">引用について</h1>
<p>引用のサンプルです。</p>
<p>大なり記号>を使うことで引用になります。</p>
<blockquote>
<p>あなたのぶどう畑の実を取りつくしてはならない。
またあなたのぶどう畑に落ちた実を拾ってはならない。
貧しい者と寄留者とのために、これを残しておかなければならない。
わたしはあなたがたの神、主である。
レビ記 19:10
</p>
</blockquote>
<p>メールなどで返信した時の形式とよく似ています。</p>
筆者はhtmlの方は、ブラウザでレンダリングしないと読む気が起こりません。
手書きで書くのはもっと気が向きません。
※もちろんこのhtmlもmarkdownから生成したものですよ
この比較だけでもmarkdownの手軽さはご理解いただけると思います。
本稿の趣旨から外れるので紹介はしませんが、
ここで紹介した機能以外にもモダンなエディタではmarkdownを便利に扱う仕組みがたくさんあります。
Markdownの方言とdev.toで利用する形式について
htmlはW3CやWHATWGという団体が頑張って標準化していますが、Markdownはまだ標準化が進んでいません。
CommonMarkやIETFの提案など、それらしい標準化の活動もありますが、
まだまだ方言を利用せざるを得ない段階です。ちなみに方言の代表的なものは以下があります。
- github flavored markdown
- Markdown Extra
- Stack Overflow
- Maruku
- はてなブログやQiitaが独自に拡張しているもの
といっても差分は少しだけです。
本記事で紹介しているものは画像の貼り付け以外は、どのMarkdownでも使えるはずです。
- 見出しは
#で連ねて作る - リンクは
[画面表示テキスト](http://から始まるURL)で書く - 箇条書きは
-を先頭にした行を開業することで可能 - 他人の文章の引用は
>を先頭につけた行で行う - 画像の掲載は以下の通りです
これだけjekyllの方言です。ごめんなさい。
-
コードブロックはbacktick(`)を使う
- JISキーボードの方はShift + @マークで出ます。
- 行中に書く場合はbacktickは1つで囲みます
- 別のブロック要素に分けたい場合はbacktickは3つで囲みます
コードブロックの記述例を以下に示します。
上記のmarkdownの記述が記事中に以下のように表示されます。
dev.toではjekyllというツール用の形式のmarkdownを利用します。
上記の要素だけでdev.toの記事は十分作成できますが、jekyll用のさらに発展的な構文が使いたい場合は
- jekyll markdown syntaxやjekyll markdown cheetsheetなどで検索する
- jekyllのチュートリアルを学ぶ
などで理解を深めてください。
以上になります。
本投稿を参考に皆様が素晴らしい記事を投稿いただけると幸いです。
参考リンク
備考
- 掲載サンプルのmrkdown→html変換に以下のツールを利用しました。
- md2pdfをお借りしてmarkdownからhtmlに変換しました
- HTML Formatterをお借りしてhtmlのindentを整えました。
- 念のため補足:dev.toの投稿に上記を使った変換作業は不要です。
Top comments (0)