長い間テーマストアで公開されているテーマを使ってはてなブログを書いてきましたが、ここ2,3年は他の技術記事サービスに比べてスタイル的に読みにくいなぁと感じていました。そこで、自分にとって技術記事を読みやすいはてなブログテーマCodeFocusを作成しました。

CodeFocus

CodeFocus自体の紹介はテーマの紹介記事やカスタマイズ記事で書いたので、ここではなぜCodeFocusを作成したのかを書いていきます。

技術記事を読みやすいテーマを作ってみたい
技術記事を書きやすい、読みやすいとは?
追加機能
生成AIを使う
まとめ
参考記事

技術記事を読みやすいテーマを作ってみたい

数年ブログを書いていると、ブログの流行りや飽きでテーマを変えたくなることがあります。QiitaやZenn、dev.toなど技術ブログを書くためのサービスが増え、記事が書きやすいだけでなくはてなブログよりも読みやすく感じるサービスが増え、毎日読んで刺激を受けていることも影響している気がします。

はてなブログはテーマストアに公開されているテーマのおかげでサクッと見た目を変更できます。ただ、技術記事の読みやすさというよりシンプル、レスポンシブ、写真の見栄えを重視したテーマが多いと感じます。もちろん技術記事を書くことを想定したテーマもあるのですが、好みとばっちり合うものがなく何かしら割り切ってました。そもそもはてなブログは技術ブログだけを対象にしたサービスではないため、Qiita・Zennと同等の読みやすさを求めるのも酷な話ですしね。

ちょうど生成AIが自分で盛り上がっていたこともあり、はてなブログで技術記事を書きやすく・読みやすいテーマを作ることにしました。あまり万人向けは目指していません。

技術記事を書きやすい、読みやすいとは?

ぼんやりとはてなブログよりも読みやすいサービスが増えたと書きましたが、技術記事を読みやすいとはどういうことでしょうか? CodeFocusを作成するにあたり、Zenn、Note、dev.toなどの記事スタイルがなぜ読みやすいのか調査しました。以下に各サービスの特徴をまとめます。

Zenn

Zennは、PC/タブレットで2カラム、スマホでシングルカラムです。2カラムだと右カラムに目次が固定されており、シングルカラムだとヘッダーに目次が固定されます。また目次は現在の見出し箇所を追随してハイライト表示します。目次にいつでもアクセスでき、記事全体に対して今どこにいるかが直感的に分かるので、記事が長くなっても読みやすさを保っています。

本文は全体的にシンプルなデザインで、1行あたりの高さが広く、段落間や見出しh1-6の間に十分な余白を設けています。また、見出しレベルh1・h2で下線を引いています。本文中のリンクは青色でリンクを意識しやすくなっています。技術記事は引用が多くなりやすいので、リンクが見やすいのは必要な配慮だと感じます。

個人的にコードブロックが好みです。背景が十分に濃い色で、コードのハイライトも見やすくなっています。さらにコードブロックの折り返しがデフォルトで無効になっており、スマホでもコードが読みやすいです。折り返しのON/OFF切り替えが可能で、コードブロックコピーもあるので困ったことがありません。

余計な装飾がなく、見出し装飾もシンプル
タイトルは中央寄せ
PCは記事本文が708px、タブレットが517px、スマホが90％幅と、はてなブログよりも広めにとっている
目次に記事の途中でアクセスでき、いつでもアクセスできる/どこまで読んだか分かる
本文の色合いは白黒ベースメインでリンクが青色というシンプルな色合い
本文以外のリンクは黒色で、リンクの色は青色で目に留まるように
行の高さが1.9と広く、段落間も広くセクションの違いが分かりやすい
コードブロックセクションの背景色が濃く、ハイライトの色も見やすい
コードブロックの折り返しがデフォルト無効でスマホでコードが折り返されず読み下しやすい(ON/OFF切り替え可能)
警告や注意書きのセクションが存在し目立つ

Zenn

Note

Noteは、事実上のシングルカラムと言えます。PCで左側に著者プロフィールが表示されますが、ほぼ目に入らないでしょう。目次ががなく本文ナビゲーションは重視していないようです。

本文はシンプルなデザインで、1行あたりの高さが広く、段落間や見出しh1-6の間に十分な余白を設けています。また、見出しレベルで下線は一切引いていません。本文中のリンク色が本文と変わらない代わりに下線が引かれています。

Noteはたくさんの記事がありますが、技術記事の割合は少ないようです。調べてみると「目次機能がない」「コードブロックのハイライトが乏しい」「本文スペースが狭いため縦に伸びがち」など、技術記事が読みにくく感じます。通常の文章だと特に読みにくく感じないのですが、技術記事だとちょっと弱く感じました。

余計な装飾がなく、見出し装飾もない
タイトルは左寄せ
PCは記事本文が620px、タブレットが460px、スマホが100％幅と、はてなブログよりも広めにとっている
目次がなく、記事の途中でどこまで読んだか分からない
本文の色合いは白黒ベースメインでリンクも黒というシンプルな色合い
タイトルと本文以外のフォントは小さく目立たせない
本文下の他記事の区切りがシンプルにまとまっている
行の高さが1.5と狭め、段落間は広くセクションの違いが分かりやすい
コードブロックは黒背景、コードハイライトは4色
コードブロックの折り返しがデフォルト無効でスマホでコードが折り返されず読み下しやすい(ON/OFF切り替えなし)
警告や注意書きのセクションがない

Note

個人的に、本文下の「他記事へのリンク」セクションの表示が揃っていて好みです。タブレット以上の画面サイズで2列表示、それぞれは上から順に画像、タイトル、著者+日付、お気に入りなどが表示されます。スマホで1列表示、左にタイトルとメタ情報、右に画像が表示されます。目が留まりやすいです。

タブレット表示

スマホ表示

dev.to

dev.toは、PC/タブレットで2カラム、スマホでシングルカラムです。2カラムだと右カラムにプロフィールと広告が固定されています。目次はありません。

本文はシンプルなデザインで、1行あたりの高さが狭く、段落間や見出しh1-6の間に十分な余白を設けています。また、見出しレベルで下線は一切引いていません。本文中のリンクは青色でリンクを意識しやすくなっています。dev.toの記事は見出しの頭に絵文字を使っている記事が多いので、下線がなくても以外と目に留まります。

個人的にコードブロックを全画面にするボタンが興味深いです。また、ZennやNoteと違って、基本的にすべて左寄せしています。ログイン以外は左寄せで、英語サイトあるあるな統一感です。

余計な装飾がなく、見出し装飾もない
タイトルは左寄せ
PCは記事本文が748px、タブレットが584px、スマホが90％幅と、はてなブログよりも広めにとっている
目次がなく、記事の途中でどこまで読んだか分からない
本文の色合いは白黒ベースメインでリンクが青色というシンプルな色合い
タイトルと本文以外のフォントは小さく目立たせない
本文下の他記事の区切りがシンプルにまとまっている
行の高さが2と広め、段落間も広くセクションの違いが分かりやすい
コードブロックは黒背景、白文字ベース。コードハイライトは最小限でコードは読みにくい
コードブロックの折り返しがデフォルト無効でスマホでコードが折り返されず読み下しやすい(ON/OFF切り替えなし)
警告や注意書きのセクションがない

dev.to

他の気になるサイト

MagicOnionのドキュメントサイトは、3カラム構成、PCで記事本文が958pxとかなり広めです。幅が広くても読みやすいです。本文の高さが設定されていませんが、セクション間の幅は設定されているので全体的にきゅっとしている印象があります。窮屈ではないので、割と好みです。

MagicOnionドキュメント

Microsoft Learnは、3カラム構成、PCで記事本文が852pxと広めです。本文の高さは160％です。全体的に一貫性があり、まとまっている印象を受けますね。

Microsoft Learn

Google Cloudブログは、事実上のシングルカラム構成、PCで記事本文が842pxと広めです。本文の高さは1.5です。タイトルが中央寄せなのは面白いですね。

Google Cloudブログ

個人サイトのいくつかを見渡すと、割と長年スタイルは変えていないようなのでここでは割愛します。

CodeFocusのデザイン

自分が感じる技術記事を読みやすいテーマの要素を抜き出してみましょう。

シングルカラムか2カラム¹、本文やリンクの色、行の高さ、段落間の余白、見出しの装飾(h1/h2にあったほうがよさそう)、コードブロックの背景・ハイライトの色、コードブロックの折り返し、目次の有無、タイトルと本文以外は目立たせない、などが読みやすさに影響してそうです。特に技術記事ではコードブロックのハイライトと折り返しはスマホで必須のようです。記事が長くなるなら、目次を使いやすくするのも良さそうです。個人的に、Zennのデザインが割と納得感あり、Noteやdev.toの好きなところを取り入れるのがよさそうです。

これを踏まえて、CodeFocusでは以下のようなデザインを採用しています。なお、はてなブログのテーマストアはCSSのみ配布なので、JavaScriptによるカスタマイズをしなくてもデザインは整えつつ入れたい機能を追加できるようにしています。

PCでもシングルカラムにする
余計な装飾を設けず、h1/h2見出しだけ下線を引く
記事セクションの広さをPCで850px、タブレットが790px～700px、スマホは100％(余白あり)と広めに
はてなブログの[:contents]で表示される目次のコントロールを追加
- 目次のトグルを導入して目次をクリックで開閉できるように。目立たないようデフォルトは閉じるように
- JavaScriptカスタマイズでフロート目次を導入可能に、現在の見出し箇所を追随してハイライト表示
本文の色合いは白黒ベースメインでリンクを青色に
- 本文以外のリンクは黒色、太字リンクは下線を引かない、通常リンクに下線を引く
行の高さは広めに1.9、段落間や見出しh1-6の間に十分な余白を設ける
コードブロックセクションの背景色を濃く、ハイライトも見やすく
- コードハイライトライブラリは導入せず、はてなブログのコードハイライトを利用
JavaScriptカスタマイズでコードブロックの折り返しをON/OFF導入、デフォルトで折り返し無効に
警告や注意書きのセクションはなし。独自記法を設けたくない
本文下の他記事の区切りをシンプルにまとめる
JavaScriptカスタマイズでダークテーマを導入
あくまで技術記事なのでタブやグローバルナビゲーションは用いない

追加機能

CodeFocusはJavaScriptで追加できる機能を用意しています。 JavaScriptカスタマイズをしなければ機能は追加されませんが、必要な人はどうぞという感じです。はてなブログのテーマストアでテーマ入れるだけだと導入されないので、割と使われることは少なそうですが、自分がやりたいだけなのでよし。

はてなブログ組み込みキーワードである[:contents]で表示される目次を、クリックで開閉できるようにします。デフォルトは閉じており、目立たないようにしています。目次って便利なんですが、記事が長くなるほど本文トップを占有して微妙だと感じていました。目次をクリックで開閉できるようにすることで、目次を必要なときだけ表示できるようにしました。トグルを閉じておくと割とほとんどの人は開かない模様、という認識も背景にあります。

はてなブログはデフォルトで設けてほしい。

目次のトグル

フロート目次

[:contents]で目次を表示している場合、フロート目次を追加できるようにしました。 Zennや他ドキュメントサイトで本文が長いときに、目次が固定されていると便利だと感じていました。実際便利。

はてなブログはデフォルトで設けてほしい。

フロート目次

コードブロック

コードブロックの折り返し

スマホで技術記事を読んでいてつらいのが、コードブロックの折り返しです。はてなブログがそうですが、折り返されると地味に読みにくくてずっと不満でした。 CodeFocusは、コードブロックの折り返しON/OFFを切り替えられるようにしました。デフォルトは折り返し無効で、スマホでもコードが読みやすいです。

はてなブログはデフォルトで設けてほしい。

折り返しは読みにくい

折り返しなしは読みやすい

コードブロックのコピー

ずっと以前からコードブロックにあると便利なのが、コピーボタンです。割とコピー&ペーストで手元に持ってきて実行してみることは多いので、CodeFocusではコードブロックの右上にコピーボタンを追加しました。コードブロックが長かったりすると、コピーしそこねとかよくあるんですよね。

はてなブログはデフォルトで設けてほしい。

コードブロックのコピー

ダークテーマ

ダークテーマは是非に議論があると認識しています。ダークモード：ユーザーの考え方と避けるべき課題は割とそうだなぁと同意するところも多いです。とはいえ、今現在においてシステムテーマでライト/ダーク(あるいはティルト)を設定できる流れは広がっており、任意で選択できるようになりつつあります。私自身、iOSでは時間でダークテーマ・ライトテーマを切り替えています。

CodeFocusはシステムテーマを尊重しつつ、ダーク/ライトテーマを切り替えられるようにしています。 JavaScriptカスタマイズしなければダークテーマは適用されないので、使いたい人はどうぞという感じで。

ダークテーマ

生成AIを使う

CodeFocusは、GitHub Copilot(Claude Sonnet 3.7、Claude Sonnet 4)を使って開発しています。 CSSは苦手なのもあってテーマ作成を避けてたものの、生成AI使うことで完成までこぎつけられたのは良い体験でした。

SCSSを使っているうちにCSS苦手意識が消え、インストラクションベースでの開発に夢中になれたのも良かったです。

テーマのコードベース

はてなブログがボイラーテンプレートとなるテーマhatena/Hatena-Blog-Theme-Boilerplate公開しているので、それぞベースに組んでいます。えらい。

Vite + SCSSを使っており、割とシンプルな構成なのでいじるには最適でした。

インストラクション

インストラクションに、はてなブログのデザインテーマ制作の手引きを食わせています．ただ、CSS回りのチェックリストとして、これを食わせるのがベターかは微妙でした。「デザインカスタマイズの仕様」あたりが一番それっぽい箇所ですが、条件付きのセレクターが多く、AIにとってデザイン構成で考慮するには厳しい感じです。文章でしじするより仕様として与える必要があるのですが、組み込みされない傾向でした。デザインテーマの手引きよりも、はてなブログ公式として「はてなブログデザインのMCP」を公開してもらえると嬉しいなぁと感じます。

インストラクションには、生成AIの動作以外にデザイン仕様もすべて書き出しています。これをCopilotに食わせることで、デザインの意図を理解してもらい、CSSを調整しています。

Playwrightテストを組む

AIで組むにあたって真っ先に考えたのが、PlaywrightでのE2Eテストです。AIでデザイン調整していると、インストラクションにかかわらず割と破壊してきます。その対策にPlaywrightのテストをCopilotに書かせています。 PlaywrightでスペックテストやE2Eテストを組むことで、変更でCSSが壊れていないかAIにフィードバックを与えます。

これでデザイン変更後はテストが通るまで修正が続くので、破壊されるケースは減りました。割とうまくいったのでおすすめです。デザインに対するテスト以外に、JavaScriptカスタマイズの機能ごとのテストも組むことで、安心して機能追加や変更ができるようになります。

playwrightテスト

テーマストアのキャッチ画像

テーマストアのキャッチ画像もAIに書かせています。キャッチ画像は何度も調整を繰り返すので再現性が欲しくて画像生成は避けました。代わりに、CopilotがHTMLでキャッチページを用意してPlaywrightで自動的にスクリーンショットを撮るのを提示してきたので採用しています。

他のテーマを見ると、テーマストアのキャッチ画像は実際のブログスクリーンショットを埋めているケースが多いようです。幸いE2Eテストでスクリーンショットを撮るので、テストに使った画像をテーマストアのキャッチ画像のHTMLに埋め込むだけで済みました。レイアウトもHTMLで組んでいるので、修正はCSSを調整するだけで済みました。便利。