CodeHilite

《 初回公開:2022/03/26 , 最終更新:未 》

原文は

旧バージョンの記事は

【 目次 】

要約

CodeHilite拡張機能は、Pygmentsを使用して標準のPython-Markdownコードブロックにコード/構文の強調表示を追加します。
この拡張機能は、標準のMarkdownライブラリに含まれています。

セットアップ

ステップ1:Pygmentsをダウンロードしてインストールする

また、PYTHONPATHにPygmentsパッケージをダウンロードしてインストールする必要があります。
CodeHilite拡張機能は、PygmentsなしでHTML出力を生成しますが、何も強調表示しません(use_pygmentsをFalseに設定するのと同じ動作)。

愚鈍人の独り言

Pygmentsはpipを使ってインストール。

ステップ2:CSSクラスを追加する

適切なルールを使用して適切なCSSクラスを定義する必要があります。
CSSルールは、HTMLテンプレートのヘッダーで定義するか、ヘッダーからリンクする必要があります。
PygmentsはCSSルールを生成できます。
コマンドラインから次のコマンドを実行するだけです。

pygmentize -S default -f html -a .codehilite > styles.css

別のcssクラス(デフォルト:.codehilite)を使用している場合は、-aオプションの値をそのクラス名に設定します。
CSSルールはstyles.cssファイルに書き込まれ、サイトにコピーしてHTMLテンプレートからリンクできます。

別のテーマを使用したい場合は、デフォルトを目的のテーマに交換してください。
システムにインストールされているテーマのリストについては、次のコマンドを実行します。(追加のテーマはPygmentsプラグインを介してインストールできます)

pygmentize -L style

詳細については、Pygmentsの優れたドキュメントを参照してください。
言語が定義されていない場合、Pygmentsは言語を推測しようとします。
それが失敗した場合、コードブロックは強調表示されません。

関連項目

GitHubユーザーrichelandは、各テーマのプレビューとともにPygmentsで機能するさまざまなCSSスタイルシートを提供しています。
cssクラスは.highlightが使われています。
したがって、richelandのCSSスタイルを使用する場合は、css_classオプションをオーバーライドする必要があります。
ただし、Python-Markdownプロジェクトは、richelandのCSSスタイルが使用しているバージョンのPygmentsで機能することを保証するものではありません。
完全な互換性を確保するには、Pygmentsの独自のインストールからCSSルールを生成する必要があります。

構文

CodeHilite拡張機能は、1つの例外を除いて、通常のMarkdownコードブロックと同じ構文に従います。
highlighterは、コードブロックに使用する言語を知る必要があります。
コードブロックに含まれる言語をhighlighterに伝える方法は3つあり、それぞれ結果が異なります。

Note

言語識別子の形式は、linenumsがNone(デフォルト)に設定されている場合にのみ行番号の表示に影響します。
TrueまたはFalseに設定されている場合(以下の使い方を参照)、識別子の形式は行番号の表示に影響を与えません。
これは、コードブロックの言語を定義する手段としてのみ機能します。

Shebang (path付き)

コードブロックの最初の行にシバンが含まれている場合、言語をそれから取得して、行番号が使用されます。

    #!/usr/bin/python
    # Code goes here ...

結果は次のようになります。

1
2
#!/usr/bin/python
# Code goes here ...

Shebang (path無し)

最初の行にShebangが含まれているが、シバン行にパス(単一の/またはスペースさえ)含まれていない場合、その行は処理前にコードブロックから削除されます。
行番号は使用されます。

    #!python
    # Code goes here ...

結果は次のようになります。

1
# Code goes here ...

コロン

最初の行が3つ以上のコロンで始まる場合、コロンに続くテキストは言語を識別します。

    :::python
    # Code goes here ...

結果は次のようになります。

# Code goes here ...

コロン構文で強調するために特定の行を選択できます。

    :::python hl_lines="1 3"
    # This line is emphasized
    # This line isn't
    # This line is emphasized

結果は次のようになります。

# This line is emphasized
# This line isn't
# This line is emphasized

Note

hl_linesは、「強調表示された行」を意味するPygmentsのオプションにちなんで名付けられました。

言語が定義されていない時

CodeHiliteは完全な下位互換性があるため、言語を定義しないコードブロックが検出された場合、ブロックは単に<pre>タグでラップされて出力されます。

    # Code goes here ...

結果は次のようになります。

# Code goes here ...

そのソースを見てみましょう:

<div class="codehilite"><pre><code># Code goes here ...
</code></pre></div>

Note

言語が定義されていない場合、Pygmentsハイライトエンジンは言語を推測しようとします(guess_langがFalseに設定されている場合を除く)。
失敗すると、上記と同じ動作が発生します。

使い方

一般的な拡張機能の使用法については、拡張機能を参照してください。
拡張機能の名前としてcodehiliteを使用します。
拡張機能の構成については、ライブラリリファレンスを参照してください。

出力を構成するために、次のオプションが提供されています。

  • linenums: Pygmentsのlinenosフォーマッターオプションのエイリアス。
    可能な値は、yesの場合はTrue、noの場合はFalse、autoの場合はNoneです。
    デフォルトはNoneです。
    Trueを使用すると、言語の識別にコロン(:::)を使用している場合でも、すべてのコードブロックに行番号が強制されます。
    Falseを使用すると、言語の識別にshebangs (#!)を使用している場合でも、すべての行番号がオフになります。

  • guess_lang: 自動言語検出。
    デフォルトはTrueです。
    Falseを使用すると、Pygmentsが言語を推測できなくなり、言語を明示的に設定した場合にのみブロックが強調表示されます。

  • css_class: Pygmentsのcsscクラスのフォーマッターオプションのエイリアス。

  • pygments_style: Pygments HTMLフォーマッタスタイル(ColorScheme)。
    デフォルトはdefaultです。

    Note

    これは、noclassesがTrueに設定されている場合にのみ役立ちます。
    それ以外の場合は、エンドユーザーがCSSスタイルを提供する必要があります。

  • use_pygments: 出力の生成におけるPygmentsの使用を指定します。
    True(デフォルト)でPygmentsが使用可能な場合、CodeHiliteはPygmentsを使用して出力を分析およびフォーマットします。
    さらに、Pygments> = 2.4を使用している場合、出力は<code>タグでラップされますが、以前のバージョンではラップされません。
    それ以外の場合、Pygmentsは使用されません。
    言語がコードブロックに定義されている場合、HTML5仕様で提案されている方法でクラスとして<code>タグに割り当てられ、ブラウザのJavaScriptライブラリでコードブロックを強調表示するために使用できます。
    プレフィックスをカスタマイズするには、lang_prefixオプションを参照してください。

  • lang_prefix: HTMLの<code>タグに割り当てられた言語クラスの前に付けられたプレフィックス。
    デフォルトはlanguage-
    このオプションは、use_pygmentsがFalseの場合にのみ適用されます。これは、Pygmentsが言語プレフィックスを含めるオプションを提供していないためです。

  • その他のPygmentsのオプション: 他のすべてのオプションは受け入れられ、Pygmentsのレクサーとフォーマッターに渡されます。
    したがって、有効なオプションには、htmlフォーマッターまたはコードの言語が使用するレクサーによって受け入れられるすべてのオプションが含まれます。
    無効なオプションではエラーは発生せずに無視されます。

ささいな例:

markdown.markdown(some_text, extensions=['codehilite'])
ページのトップへ戻る