技術ブログの「ソースコード」表示を効果的にカスタマイズする方法

プログラミングなどの技術記事を書く際に欠かせないのが「ソースコード」の表示です。極端な話、エンジニアであれば、文章を読まなくても見出しとソースコードさえ追えば、ある程度の内容がわかってしまうものです。従ってブログでのソースコードの見せ方には一工夫加えてこだわりたいところですね。当ブログでも技術系の記事をよく書くのでソースコードをよく扱っています。先日、当ブログのソースコード周りを見直しました。今回は当ブログのソースコードの表示で使っているテクニックをいくつか紹介します。

現在の当ブログのソースコードの表示は以下のようになっています。

import React from 'react';

export default class Code extends React.Component {
  constructor() {
    super();
    state = {
      value: null,
    };
  }
  render() {
    return (
      <div>
        <h1 className="title">Hello World</h1>
      </div>
    );
  }
}

以下のような特徴があります。（リンクをクリックするとそれぞれの実装方法に進みます。）

そのままソースコードを貼り付けられる
シンタックスハイライトに対応している
monokaiテーマを使用している
行数の表示に対応している
表示にエディタ風フォントを使用している
強調したい部分にマーカーをつけている
ソースコード内が書き込み可能となっている
ソースコード枠の横幅を自由に変更できる

それぞれの実装方法を以下より紹介していきます。参考にしてください。

ソースコードを表示する

まず、基本中の基本ですね。エディタなどで書いたコードをそのままブログに貼り付けようとした場合、br要素などをつけないと改行が維持されません。毎回ソースコードの改行位置にbrをつけたりするのは面倒です。そこでpre要素を使ってソースコードを表示させるようにします。

pre 要素 – HTML | MDN

当ブログでは、以下のようにpre要素とセマンティックのためにcode要素を使ってソースコードをマークアップしています。

<pre><code>
<!-- ここにソースコードを貼り付ける -->
</code></pre>

pre要素やcode要素でマークアップした箇所は、code要素において等幅フォントで表示されるようになっています。

code 要素 – HTML | MDN

なお、HTMLタグを書く場合、例えばdiv要素をそのまま<div>と記述したら、そのままタグとして認識されてしまい、文字列として表示されないので注意が必要です。<div/<とエスケープして書く必要があります。かつては、xmp（example）要素というHTML要素をHTMLとして解釈せず、等幅フォントで表示してくれる要素がありましたが、残念なことに現在は廃止されています。

xmp要素の代替として、上記で紹介したようにpre要素とcode要素を使って、タグをエスケープして書くことが推奨されています。ただ、いちいちエスケープするのは面倒だと思った場合は、それなりに対策方法はあるようです。以下をお試しください。

HTMLコードをそのまま表示させたい｜teratail

ソースコードに色をつけて表示する（テーマとシンタックスハイライト対応）

上記のようにpre要素とcode要素でソースコードをマークアップすれば、ソースコードの表示が可能となります。しかしまだ見た目が素っ気ないままです。よくあるエディタのように色をつけたりすることで、もっとソースコードが見やすくなります。これを実現するには、JavaScriptのライブラリを使うのが手っ取り早いです。当ブログでは、Googleが開発している「code-prettify」というライブラリを使ってソースコードのシンタックスハイライトを実装しています。

google/code-prettify: Automatically exported from code.google.com/p/google-code-prettify

code-prettifyを実装するには簡単です。CDN版があるので、以下の1文を追加する追加するだけでOKです。

<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>

シンタックスハイライトを提供させたいソースコードの要素にclass=”prettyprint”を付けると、その要素内のソースコードに色がつくようになります。

<pre><code class="prettyprint">
.elem {
  font-size: 16px;
}
</code></pre>

なお、表示させるソースコードがCSSの場合は、さらにlang-cssを追加します。

<pre><code class="prettyprint lang-css">
<!-- ここにソースコードを貼り付ける -->
</code></pre>

ダウンロード版を使う

「code-prettify」にはダウンロード版もあります。以下よりダウンロード可能です。

「code-prettify」をダウンロードする

「code-prettify」をダウンロードして使う場合は、まず以下のようにCSSファイルとJSファイルをページに読み込むようにします。

<link href="prettify.css" type="text/css" rel="stylesheet">
<script type="text/javascript" src="prettify.js"></script>

CDN版は自動で処理が走るようになっていますが、ダウンロード版はページが読み込まれた段階で処理を走らせるメソッドを呼び出してあげる必要があります。

<body onload="prettyPrint()">

テーマを指定する

「code-prettify」には、テーマを指定するためのskinが用意されています。白ベースのものや黒ベースのものなどよくエディタにあるやつです。当ブログでは、Sublime Textでお馴染みの「monokai」というテーマを使っています。

使えるテーマは以下のようにいろいろ用意されています。

テーマ用のファイルはcssファイルになっています。使いたいテーマを選んだら、ダウンロードしてlink要素を使ってページに読み込むようにします。デフォルトのCSSファイルをすでに読み込んでいる場合は、それを外します。

行数を表示する

ソースコードに行数を表示させるも、上記で紹介した「code-prettify」で実装可能です。以下のように行数を表示させたい要素にprettyprintと一緒にlinenumsというclass名をつけます。これで行数が表示されるようになります。

<pre><code class="prettyprint linenums">
<!-- ここにソースコードを貼り付ける -->
</code></pre>

当ブログの場合、行数をリストの外側に表示させるために、以下のようにlist-style-position: outside;を指定しています。

li.L0, li.L1, li.L2, li.L3, li.L4, li.L5, li.L6, li.L7, li.L8, li.L9 {
  list-style-position: outside;
  margin-left: 36px;
  padding-left: 16px;
}

行数をリストの外側に表示させるとソースコード枠からはみ出してしまうので、margin-legt: 36px;を指定しています。また、行数とコードの間の距離はpadding-leftプロパティで調整可能です。

list-style-position – CSS | MDN

ソースコードをエディタ風フォントで表示する

ソースコードをそれらしく見せるには、フォント（font-family）にも気を配る必要があります。ブログの記事と同じフォントを使っていたら、ソースコードらしさが出ません。記事に最適なフォントがあるように、ソースコードに最適なフォントがあります。

当ブログでは、実際のエディタ「Atom」で使われているフォントを使うようにしました。以下のようにfont-familyを指定しています。

code {
  font-family: Menlo, Consolas, 'DejaVu Sans Mono', monospace;
}

また、フォントのサイズや行間なども、本文に合わせるのではなく、ソースコード用に以下のように指定しています。ちなみに当ブログの本文は、font-size: 17px; line-height: 1.8;となっています。

code {
  font-size: 14px
  line-height: 1.4;
}

[参考]

ソースコード内にマーカーを実装する

ソースコード内で強調したい箇所にマーカーを引いて表示させると効果的です。当ブログでは、強調したい箇所にはem要素でマーキングするようにして、以下のようにCSSでスタイルを指定しています。

em {
  font-style: norma;
  margin-left: -16px;
  margin-right: -16px;
  padding-left: 16px;
  padding-right: 16px;
  background-color: #424242;
  display: inline-block;
  width: 100%;
}

以下のようにem要素でマークアップした箇所は、マーカーを引いたようになりまります。

<pre><code class="prettyprint linenums">
em {
  font-style: norma;
<em>  margin-left: -16px;
  margin-right: -16px;
  padding-left: 16px;
  padding-right: 16px;
  background-color: #424242;
  display: inline-block;</em>
  width: 100%;
}
</code></pre>

ソースコード内を書き込み可能にする

これは完全にお遊び機能ですが、当ブログのソースコードは、自由に書き込みできるようになっています。ソースコードをペースト先のコードに合わせてコピーできるようにするためです。

ある要素を編集可能にする方法は、実に簡単です。編集可能にしたい要素に対してcontenteditable属性をtrueとして指定するだけで、その要素を編集可能にすることができます。

Content Editable – HTML | MDN

ただ、毎回ブログの記事内でソースコードを書く際に、contenteditable属性を付けるのは面倒なので、JavaScriptで自動で付与されるようにしておくと楽です。当ブログでは、jQueryで以下のようにしてcontenteditable属性をcode要素に付与しています。

function contentEditable() {
  const code = $('.prettyprint');
  code.attr({
    contenteditable: true,
    spellcheck: false,
  });
}

window.onload = () => contentEditable();

それからソースコードを編集可能にすると、ブラウザのコードチェック機能が走るようになり、所々で赤い点線が表示されるようになります。これを表示させたくない場合は、上記の通り併せspellcheck属性をfalseとして指定します。

spellcheck – HTML | MDN

ソースコードの表示域の横幅を可変にする

これまたお遊び機能となります。当ブログの本文の横幅は728pxとなっていますが、表示させるソースコードによっては、1行では収まりきれず、改行されてしまう場合があります。（コードの書き方が悪いと言えば悪いんですが、）改行されてしまうと可読性も悪くなってしまうので、ソースコードの要素の横幅を手動で伸ばせるようにしています。ソースコード枠の右下をドラッグすることで、サイズの変更ができます。

要素のサイズを自由に変更できるようにするには、CSSのresizeプロパティを使います。指定する値によって、縦、横、全方向と変更できる方向を決められます。

resize – CSS | MDN

当ブログでは横方向のみ可変としています。ソースコードは以下のようになっています。

code {
  overflow: auto;
  resize: horizontal;
}

なお、overflowプロパティの値がvisibleとなっている場合は、resizeプロパティが機能しなくなるので、併せてoverflow: auto;を指定しています。

まとめ

最初にも書いたように、エンジニアブログにとってソースコードは文章と同じくらい大事なものです。従って、ソースコードの表示には相当気を配っても良いかなと思っています。GitHubやGist、CodePenなどのサービスを使ってソースコードを埋め込むことも可能なので、お好みで外部のサービスも使っても良いかと思います。

今回紹介した方法で、もし取り入れてみたいものがありましたら、ぜひ参考にしてみてください。当ブログでも引き続きソースコードの表示に効果的なものがあれば実装していく予定です。エンジニアブログをどんどん盛り上げていきましょう！

カテゴリー: Web技術
CSS HTML5 JavaScript webデザイン WordPress

maesblog