Mojikumi

Documentation

段階的に導入する

導入は、スクリプトを1つ読み込むか、CSSプリセットを読み込むところから始まります。標準CSSだけでは揃わない環境には、DOMフォールバックを追加してください。ReactでもMarkdown / MDXでも手順は変わらず、本文の文字列に手を加えないという方針も共通です。

01

スクリプトタグで使う

ビルド設定を持たないサイトでは、スクリプトを1つ読み込むだけで動作します。CSSはバンドルに含まれているため、読み込むファイルは1つです。設定はタグの属性で渡し、読み込み後に追加された記事も自動的に対象になります。

HTML
<script
  src="https://cdn.mojikumi.jp/v1/mojikumi.min.js"
  data-target=".entry-content"
  data-style="article"
></script>
属性既定値内容
data-targetauto本文のセレクター。autoは既知の本文要素を順に探します
data-stylearticlearticle（記事向け）、book（書籍風）、headline（見出し重視）
data-precisionautonative、auto、fullのいずれか
data-excludeなし追加で除外するセレクター。カンマ区切り
data-csstrue同梱CSSを読み込むかどうか
data-autotruefalseにするとMojikumi.start()を呼ぶまで何もしません

02

CSSだけで使う

CSSプリセットを読み込み、本文の要素にクラスを付けます。標準CSSに対応したブラウザなら、これだけで約物まわりの空白が詰まります。ビルド設定の変更もJavaScriptの追加も不要です。プリセットはbook、web、editorial、minimalの4種類で、それぞれ詰めの強さが異なります。

TSX
import "mojikumi/css";

<article lang="ja" className="mjk mjk-book">
  <p>『Webの日本語』を端正にする</p>
</article>

03

DOMフォールバックを追加する

標準CSSが未実装のブラウザでも同じ表示を得たい場合は、DOM層を追加します。約物が連続する箇所や、行頭・行末に置かれた括弧など、CSSだけでは揃わない位置を実行時に計測して補正する層です。precisionをautoに設定しておけば、対応済みのブラウザでは処理そのものが実行されません。

TypeScript
import "mojikumi/css";
import { mojikumi } from "mojikumi";

const instance = mojikumi(".article", {
  preset: "book",
  precision: "auto"
});

04

Reactで使う

サーバーでは通常のHTMLを出力し、ブラウザに届いた時点で不足分だけを補います。要素を囲むComponentと、既存の要素に適用するHookのどちらでも利用できるため、現在のレイアウトを組み替える必要はありません。

TSX
import { Mojikumi } from "@mojikumi/react";

export function Article({ children }) {
  return (
    <Mojikumi as="article" preset="book">
      {children}
    </Mojikumi>
  );
}

05

Markdown / MDXで使う

rehypeプラグインとして組み込むと、記事本文にプリセットが適用されます。原稿のMarkdownは変更する必要がなく、書き手が字組みを意識することもありません。コードブロックと数式は処理の対象から除外されるため、記号の並びが崩れることはありません。

TypeScript
import rehypeMojikumi from "@mojikumi/rehype";

export default {
  rehypePlugins: [
    [rehypeMojikumi, { preset: "editorial" }]
  ]
};

06

プリセットを選ぶ

プリセットは、どの調整を行うかの組み合わせです。迷う場合はwebを選んでください。書籍に近い体裁が必要ならbook、見出しの文節改行を優先するならeditorial、約物の重なりだけを詰めたいならminimalが適します。nativeはブラウザの実装だけを使い、JavaScriptによる補完を行いません。

調整webbookeditorialminimalnative
連続する約物○○○○○
行頭の調整○○○—○
行末の調整条件付き○○—○
和欧文間○○——○
段落の字下げ—1em———
見出しの文節改行——○——
JSによる補完○○○○—

07

ブラウザの実装との切り替え

precisionは、標準CSSとDOM補完のどちらをどこまで使うかの指定です。既定のautoでは、ブラウザが実際に約物を詰めているかを実測してから判断します。構文としては対応していても表示が変わらない実装があるため、対応表ではなく実測で切り替えています。

値動作使いどころ
native標準CSSのみを使用しますJavaScriptを増やしたくない場合
auto不足している処理だけを補います通常はこれで十分です
full常にDOM補完を適用します検証時や、実装差を確認する場合

08

適用範囲を変える

コード、フォーム、編集中の領域、SVG、MathMLは、指定がなくても対象から外れます。任意の範囲を外したい場合は、その要素にdata-no-mojikumiを付けます。まとめて外すなら、excludeやdata-excludeにセレクターを渡します。

HTML
<span data-no-mojikumi>console.log("日本語")</span>
  • 既定の除外：script、style、code、pre、kbd、samp、textarea、input、select、option、contenteditable、svg、math
  • data-no-mojikumiを付けた要素と、その内部
  • data-excludeまたはexcludeで追加したセレクター

09

プログラムから操作する

スクリプトタグで読み込むと、グローバルのMojikumiから操作できます。data-autoをfalseにしておけば、開始のタイミングも自分で決められます。npmから使う場合は、同じ処理をmojikumiパッケージのmojikumi関数が担当します。

JavaScript
Mojikumi.start({ target: ".article", style: "book" });
Mojikumi.refresh();
Mojikumi.stop();
関数内容
start(options)適用を開始し、以降に追加された記事も対象にします
refresh()行頭・行末の判定をやり直します
stop()生成した要素とクラス、読み込んだCSSをすべて取り除きます

10

自分のサーバーへ置く

CDNを使わない場合は、npmパッケージに含まれる同じファイルを自分のサーバーへ置けます。node_modules/mojikumi/dist/mojikumi.browser.jsを公開ディレクトリへコピーし、srcをそのパスに変えるだけです。動作は変わりません。

HTML
<script src="/assets/mojikumi.min.js" data-style="article"></script>

11

元に戻す

スクリプトタグを消す、あるいはstop()を呼ぶと、その場で元の状態に戻ります。Mojikumiは本文の文字列を書き換えないため、取り外したあとに痕跡は残りません。

  • 生成した要素とクラスを取り除き、変更した属性を元の値へ戻します
  • 本文の文字列は変更していないため、保存されたデータには何も残りません
  • スクリプトが読み込めなかった場合も、本文はそのまま表示されます

12

設計方針

  • まず標準CSSで動作し、ブラウザが対応していればそれだけで完結します
  • 本文の文字列は書き換えないため、コピーした文章も読み上げの内容も元のまま保たれます
  • ブラウザの対応が進むほど、読み込まれるコードは自然に減っていきます
  • 約物メトリクスを備えていない書体では、詰めを適用しません

次のステップ

実際の文章で見比べる

Playgroundへ