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

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

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

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>
    );
  }
}

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

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

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

ソースコードを表示する

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

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

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

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

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

上記のようにpre要素とcode要素でソースコードをマークアップすれば、ソースコードの表示が可能となります。しかしまだ見た目が素っ気ないままです。よくあるエディタのように色をつけたりすることで、もっとソースコードが見やすくなります。これを実現するには、JavaScriptのライブラリを使うのが手っ取り早いです。当ブログでは、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」をダウンロードして使う場合は、まず以下のように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プロパティで調整可能です。

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

ソースコードをそれらしく見せるには、フォント(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’として指定するだけで、その要素を編集可能にすることができます。

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

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

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

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

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

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

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

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

code {
  overflow: auto;
  resize: horizontal;
}

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

まとめ

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

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

コメント一覧

  • 必須

コメント