Jektex 0.2.0 – LaTeXレンダリング用Jekyllプラグインが約10倍高速化

サーバーサイドでキャッシュされた、超高速なLaTeXレンダリングのためのJekyllプラグインで、マクロもサポートしています。LaTeXとMarkdownの快適さを、サイトを肥大化させるJavaScriptなしで楽しんでください。このプロジェクトはKaTeX.orgによって推奨されています。 特徴 - Jekyllレンダリング中にLaTeX数式をレンダリングします - クライアントサイドのJavaScriptなしで動作します - 他のサーバーサイドJekyll LaTeXレンダラーよりも高速です - ユーザー定義のグローバルマクロをサポートします - I/O効率の良いキャッシュシステムを備えています - レンダリング中の式の数を動的に通知します - セットアップが非常に簡単です - Jekyllのワークフローやプロジェクト構造に干渉しません - 無効な式を文書内でマークし、レンダリング中にその位置を出力します - コードブロックやインラインコード内のLaTeXはそのまま残すため、LaTeXについて書くことができます - kramdownがスキップする生のHTMLブロック内の数式をレンダリングします - 適切なデフォルト設定で高度に設定可能です - キャッシュに古い設定でレンダリングされた式が含まれないことを保証します - 2つの主要なLaTeX表記をサポートします 使用方法 Jektexは、組み込みのKramdownの数式表記と、新しいLaTeXのみの数式表記の両方をサポートしています。 Kramdown表記 インライン数式 段落内で、数式を2組のドル記号（$$）で囲みます。 Lorem ipsum dolor sit amet, consectetur $$e^{i heta}=\cos(\theta)+i\sin(\theta)$$ adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 表示数式 数式を2組のドル記号（$$）で囲み、前後に空行を入れます。 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. $$ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) $$ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. なぜJektexはインライン数式に従来の単一の$、表示モードに二重の$$を使用しないのか？ これはkramdown（Jekyllのmarkdownパーサー）の動作方法であり、この規約を尊重することにしました。これにより、このプラグインはより一貫性があり、普遍的になります。詳細については、このissueを参照してください。 生のHTMLブロック内の数式 Kramdownは、ブロックレベルのHTMLタグ内のmarkdownを処理しないため、<div>$$\beta$$</div>のような数式は変換されずに残ります。Jektexは、変換後にこれらの残った$$数式を見つけて、自身でレンダリングします。 行だけで独立した数式は表示モードでレンダリングされ、テキストフロー内の数式はインラインでレンダリングされます。 <div>The inline formula $$e^{i\theta}$$ sits in text flow. $$ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) $$ </div> これはmarkdownソースファイルにのみ適用され、pre、code、scriptなどのタグ内では決して適用されません。 特定の数式のレンダリングを防止するには、それを\$\$としてエスケープするか、コードスパンに入れることができます。 HTMLブロックの内容をkramdownに処理させたい場合は、タグにmarkdown="1"属性を与えてください。 LaTeX数式モード表記 インライン数式 数式を2つのエスケープされたブラケット（\( \)）で囲みます。テキスト内の位置は関係ありません。 Lorem ipsum dolor sit amet, consectetur \(e^{i\theta}=\cos(\theta)+i\sin(\theta)\) adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 表示数式 数式を2つのエスケープされた角括弧（\[ \]）で囲みます。テキスト内の位置は関係ありません。 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. \[ \left[ \frac{-\hbar^2}{2\mu}\nabla^2 + V(\mathbf{r},t)\right] \Psi(\mathbf{r},t) \] Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. ロゴマクロ jektexロゴ用の組み込みマクロがあります。\jektexとして使用できます。 設定 Jektexは、_config.ymlファイルを通じて高度に設定可能です。不明なオプションや無効な値はビルド中に報告され、デフォルト値にフォールバックします。 キャッシュの無効化 disable_disk_cache オプションでキャッシュを無効にできます。キャッシュはデフォルトで有効になっています。これはJekyll自体のオプションなので、以下のオプションとは異なり、_config.ymlのトップレベルに配置する必要があります。jektexキーの下ではありません。 disable_disk_cache: true Jekyllの公式ウェブサイトで詳細を確認できます。 キャッシュ場所の設定 デフォルトでは、Jektexキャッシュは.jekyll-cacheディレクトリに保存されます。これにより、jekyll cleanを呼び出したときに削除されます。キャッシュの削除を防ぐか、キャッシュの場所を変更するには、_config.ymlでcache_dirを指定できます。 jektex: cache_dir: ".jektex-cache" ファイルの無視 デフォルトでは、JektexはJekyllによってレンダリングされるすべてのファイルでLaTeXをレンダリングしようとします。これは、LaTeXを含む抜粋を含むRSSフィードをレンダリングする場合など、望ましくない場合があります。Jektexは、ignoreオプションを使用してこれを解決します。 jektex: ignore: - "*.xml" - "README.md" - "_drafts/*" 従来のワイルドカード（*）を使用できます。この設定例では、すべての.xmlファイル、README.md、および_draftsディレクトリ内のすべてのファイルを無視します。 特定の投稿を無視する別の方法は、フロントマターでjektex属性をfalseに設定することです。 --- title: "How Jektex works" category: "Development" jektex: false layout: post --- jektexタグをtrueに設定するか、まったく設定しない場合、Jektexはその投稿のLaTeX式をレンダリングします。 マクロの使用 グローバルマクロを定義できます。 jektex: macros: - ["\\Q", "\\mathbb{Q}"] - ["\\C", "\\mathbb{C}"] はい、yaml仕様のため、バックスラッシュ（\）は別のバックスラッシュでエスケープする必要があります。 パラメータ付きのマクロを定義できます。 jektex: macros: - ["\\vec", "\\mathbf{#1}"] - ["\\addBar", "\\bar{#1}"] これはLaTeXの\newcommandの動作をシミュレートします。 Jektexの出力をサイレンスにする Jektexは、レンダリングされた/キャッシュされた方程式についてユーザーに定期的に通知します。これが望ましくない場合は、silentオプション（デフォルトはfalse）を設定できます。 jektex: silent: true KaTeXオプション KaTeXレンダリングオプションは、katex_optionsキーを通じてレンダラーに渡すことができます。キーはKaTeXドキュメントのスペル通りに正確に記述してください。 jektex: katex_options: trust: false output: htmlAndMathml strict: warn 最も役立つオプションは次のとおりです。 - trust: KaTeXが潜在的に安全でないと見なす機能（デフォルトはfalse）を切り替えます。具体的には\url、\href、\includegraphics、\htmlClass、\htmlId、\htmlStyle、\htmlDataです。 - output: htmlは、不可視のMathMLコピーを省略することで、レンダリングされた各数式のサイズを半分にします。MathMLはスクリーンリーダーが使用するものであることに注意してください。 - maxExpand: マクロ展開を制限し、暴走する再帰マクロからビルドを保護します。 JektexはdisplayMode、macros、throwOnError、globalGroupを自身で制御するため、これらのキーは無視されます（マクロは上記のmacrosオプションで定義してください）。 ドキュメント化されたKaTeXオプションの値はチェックされます。無効な値は報告され、KaTeX自体のデフォルトが使用されます。Jektexが知らないオプション名（新しいKaTeXバージョンによって追加されたものなど）は、チェックされずに渡されます。 KaTeXオプションのいずれかを変更すると、キャッシュが無効になり、次のビルドで一度すべてが再レンダリングされます。 完全な例 推奨設定: jektex: cache_dir: ".jektex-cache" ignore: - "*.xml" silent: false katex_options: trust: false macros: - ["\\Q", "\\mathbb{Q}"] - ["\\C", "\\mathbb{C}"] 設定なしはこれと同等です: jektex: cache_dir: ".jekyll-cache" ignore: [] silent: false katex_options: {} macros: [] インストール このプラグインはRubyGemとして利用可能です。 Bundlerを使用する GemfileにJektexを追加します。 group :jekyll_plugins do gem "jektex" end そしてbundle installを実行します。 Bundlerを使用しない場合 gem install jektexを実行します。 インストール後 _config.ymlファイルでJektexをプラグインリストに追加します。 plugins: - jektex そして、HTMLのheadにkatex.min.cssを追加することを忘れないでください。 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.17.0/dist/katex.min.css" integrity="sha384-vlBdW0r3AcZO/HboRPznQNowvexd3fY8qHOWkBi5q7KGgqJ+F48+DceybYmrVbmB" crossorigin="anonymous"> CSSファイルをダウンロードして、サーバーから直接アセットとしてロードする方がはるかに良いプラクティスです。KaTeXのウェブサイトで詳細を確認できます。 貢献とバグレポート バグがあれば、お気軽にご報告ください。あるいは、