UP
Admonition(助言 - 説諭、 訓戒、 警告) 		前のページへ
Python-Markdown Extensionsのつたない翻訳 		次のページへ
HeaderId

CodeHilite

初回公開：2018/01/01
最終更新：2018/01/13

「CodeHilite Extension — Python Markdown」をつたない翻訳，勝手な解釈。

【　目次　】

要約

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

セットアップ

手順1：Pygmentsをダウンロードしてインストール

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

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

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

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

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

別のテーマを使用する場合defaultと指定している部分を、目的のテーマに変更します。
あなたのシステムにインストールされているテーマのリスト（追加のテーマはPygmentsプラグインを使ってインストールできます）については、次のコマンドを実行してください：

pygmentize -L style

以下もまた参照

GitHubのユーザーrichelandは、各テーマのプレビューとともにPygmentsで動作するいくつかの異なるCSSスタイルシート
を提供している。
css_classは、そのオプションのデフォルト値(codehilite)と同じです
しかし、Python-Markdownプロジェクトは、richelandのCSSスタイルがあなたが使っているPygmentsのバージョンで動作する事を保証しない。
完全な互換性を確保するには、あなた自身のインストールしたPygmentsからCSSルールを生成する必要があります。
詳細は、Pygmentsの優れたドキュメントを参照してください。
言語が定義されていない場合、Pygmentsは言語を推測しようとします。
それが失敗すると、コードブロックは強調表示されません。

構文

CodeHilite extensionは、1つの例外を除いて、通常のMarkdownコードブロックと同じ構文に従います。
ハイライターは、コードブロックに使用する言語を知る必要があります。
コードブロックにどのような言語が含まれ、それぞれが異なる結果を持っているかを、ハイライター(highlighter)に伝える3つの方法があります。

注意

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

Shebang (path付き)

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

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

結果：

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

Shebang (pathなし)

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

    :::python
    # Code goes here ...

結果：

# Code goes here ...

訳者注：行番号使用の意味は行番号としてカウントされるという意味なのかな？

Colons

最初の行が3つ以上のコロンで始まる場合は、コロンに続くテキストが言語を識別します。
最初の行は処理前にコードブロックから削除され、行番号は使用されません。

    :::python
    # Code goes here ...

結果：

# Code goes here ...

コロン構文を使用して強調表示するために、特定の行を選択することができます。
PygmentsのデフォルトのCSSスタイルを使用するとき、強調された行は黄色の背景を持ちます。
これは読者の注意を特定の行に指示するのに便利です。

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

注意

hl_lines 「強調表示された線」を意味するPygmentsのオプションの名前です。

言語が定義されていないとき

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

    # Code goes here ...

結果：

# Code goes here ...

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

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

注意

言語が定義されていない場合、Pygmentsの強調表示エンジンは言語を推測しようとします（guess_langがFalseに設定されていない限り）。
障害が発生すると、上記と同様の動作が発生します。

使い方

extensionの一般的な使用法については、Extensionsを参照、extensionの名前として markdown.extensions.codehiliteを指定してください。

extensionsの設定については、Library Referenceを参照してください。

出力を設定するには、次のオプションが用意されています。

  • linenums: 行番号を使用します。可能な値は、yesを意味するTrue，noを意味するFalse、そしてautoを意味するNoneです。
    デフォルトはNone。

    Trueは、言語識別のためにcolons（:::）を使用する場合でも、すべてのコードブロックに行番号を付けるよう強制します。

    Falseは、言語識別にshebangs（#!）を使用している場合でも、すべての行番号をオフにします。

  • guess_lang: 自動言語検出。デフォルトはTrue。

    Falseは、Pygmentsが言語を推測することを防ぎ、明示的に言語を設定した場合にのみブロックを強調表示します。

  • css_class: ラッパーする<div>タグのCSSクラス名を設定します。
    デフォルトは codehilite。

  • pygments_style: Pygments HTML Formatterスタイル（ColorScheme）。
    デフォルトはdefault。

    注意

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

  • noclasses: CSSクラスの代わりにインラインスタイルを使用します。
    デフォルトはFalse。

  • use_pygments: デフォルトはTrue。
    Falseに設定すると、Pygmentsの使用を無効にします。

    コードブロックに言語が定義されている場合、HTML5 仕様<code>で提案されている方法でクラスにタグとして割り当てられます（代替出力は受け付けません）。
    ブラウザのJavaScriptライブラリによってコードブロックを強調表示するために使われるかもしれません。

ページのトップへ戻る