コードは、書いたあとに何度も読み返したり、少し変えて試したりするものです。
だからOJapp Blog Kitでは、コードをただ黒い箱に入れるだけでなく、言語が見えること・色で読めること・すぐコピーできること・字下げの深さを追えることを大切にしています。
この記事では、Markdownでコードブロックを書く方法と、Blog Kitで表示するときの工夫を紹介します。
まずは言語名を付ける
Markdownでは、バッククォートを3つ並べた行の後ろに言語名を書きます。言語名があると、コードブロックの上部に種類が表示され、コードに合わせた色分けが行われます。
```js
console.log("Hello, Blog Kit!");
```実際に書くと、こういうJavaScriptのコードブロックになります。
console.log("Hello, Blog Kit!");色分けでコードの役割を見つけやすく
コードの色は、キーワードや文字列などの種類を見分ける手がかりになります。長いコードでも、処理の流れを目で追いやすくなります。
function createWelcomeMessage(name) {
const message = `こんにちは、${name}さん`;
return message;
}
const message = createWelcomeMessage("おじゃち");
console.log(message);言語名は js や javascript のように、コードフェンスのすぐ後ろに書きます。たとえばJSONなら、次のようにします。
{
"title": "自分のブログ",
"language": "ja-JP",
"writeInMarkdown": true
}字下げガイドで階層を追う
処理が入れ子になると、どこからどこまでが同じ階層なのか見失いやすくなります。Blog Kitはコードの字下げに合わせて縦のガイドを表示します。
function publishArticle(article) {
if (!article.title) {
return { ok: false, reason: "タイトルがありません" };
}
return {
ok: true,
article: {
title: article.title,
published: true,
},
};
}このガイドは表示時に加わるものです。Markdownに特別な記号を足す必要はありません。コードのインデントを整えて書けば、その階層が見た目にも現れます。
コピーしてすぐ試せる
コードブロックにはコピー操作が付きます。読む人はコードを選択してドラッグしなくても、ボタンから中身をコピーできます。
npm install
npm run buildコピーされるのはコード本文です。表示用の色や枠は含まれないので、ターミナルやエディターに貼り付けてそのまま使えます。
Diffで変更箇所を見せる
設定やコードの変更を説明するときは、diff を指定すると追加行と削除行を色で見分けられます。
- const theme = "plain";
+ const theme = "vitesse-dark";
const readable = true;差分は変更点だけを短く示せるので、「変更前の全部」と「変更後の全部」を並べるより、どこを見ればよいか伝えやすくなります。
HTMLやCSSも同じ書き方
コードブロックの書き方は言語が変わっても同じです。HTMLの例なら html、CSSなら css を付けます。
<article class="post">
<h2>記事タイトル</h2>
<p>Markdownから生成された記事です。</p>
</article>.post {
max-width: 720px;
margin-inline: auto;
line-height: 1.9;
}書くときに意識すると伝わりやすいこと
コードブロックの見た目だけでなく、何を見せるかも読みやすさを左右します。
- コードの前に「何をする例か」を一文で説明する
- 記事の説明に必要な部分に絞る
- 省略した箇所がある場合は、コメントなどで分かるようにする
- 言語名を付けて、色分けと種類表示を有効にする
- 変更点を示すなら
diffを使う
行番号はあえて表示しません。行番号を追うより、コードそのものと字下げの階層に集中できる表示を目指しています。
普通のMarkdownのまま使える
コードブロックは標準的なMarkdownのコードフェンスで書けます。Blog Kit独自の記法を覚えたり、記事本文にHTMLを埋め込んだりする必要はありません。
```js
const blog = "自分の場所に公開する";
```記事の元データはMarkdownのまま手元に残ります。表示を整える仕組みはBlog Kitが担当するので、書く人は内容に集中できます。
コードを載せる記事も、読みやすく、試しやすく。これからも「書くこと」に集中できるブログを目指していきます。