py-gfm - Python-MarkdownでGFM

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

【　目次　】

py-gfm - Python-MarkdownでGFM

markdownにはGFM(GitHub Flavored Markdown)という良く知られた方言が存在する。

MarkdownでHTMLを簡単に - 愚鈍人

Python-Markdown ExtraやdelタグとinsタグのExtensionを使ってGFM的に使う事もできるが

PythonでMarkdownをGFM的に使う方法

py-gfmというExtensionsを使うとpython-markdownでGFMの記法が使えるらしい。

py-gfm 0.1.3 : Python Package Index

ドキュメントは

py-gfm documentation — py-gfm 0.1.2 documentation

以下も参照

インストール

インストールはpythonのScriptsデレクトリに移動して(私の環境ではScriptsにパスがとうしていないので)
pipを実行、
Python27とPython34に対してそれぞれインストール。

C:\home\ichi> cd C:\Python27\Scripts

C:\Python27\Scripts> pip install py-gfm
Downloading/unpacking py-gfm
  Downloading py_gfm-0.1.3-py2.py3-none-any.whl
Requirement already satisfied (use --upgrade to upgrade): markdown in c:\python27\lib\site-packages (from py-gfm)
Requirement already satisfied (use --upgrade to upgrade): setuptools in c:\python27\lib\site-packages\setuptools-7.0-py2.7.egg (from py-gfm)
Installing collected packages: py-gfm
Successfully installed py-gfm
Cleaning up...

C:\Python27\Scripts> cd "C:\Python34\Scripts"

C:\Python34\Scripts> pip install py-gfm
Downloading/unpacking py-gfm
  Downloading py_gfm-0.1.3-py2.py3-none-any.whl
Requirement already satisfied (use --upgrade to upgrade): markdown in c:\python34\lib\site-packages (from py-gfm)
Requirement already satisfied (use --upgrade to upgrade): setuptools in c:\python34\lib\site-packages (from py-gfm)
Installing collected packages: py-gfm
Successfully installed py-gfm
Cleaning up...

C:\Python34\Scripts>

動作確認

py-gfmのサンプルコード

py-gfm documentation — py-gfm 0.1.2 documentationのコードを少し変更して

py-gfmの全機能を使いたい場合はextensions引数にGithubFlavoredMarkdownExtensionクラスのインスタンスを指定

import markdown
from mdx_gfm import GithubFlavoredMarkdownExtension

source = """
Hello, *world*! This is a ~~good~~marvelous day!
Here is an auto link: https://example.org/

Le me introduce you to [task lists] (https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments):

- [ ] eggs
- [x] milk

You can also have fenced code blocks:

```
import this
```
"""

# Direct conversion
html = markdown.markdown(source,
                         extensions=[GithubFlavoredMarkdownExtension()])
print html

実行結果

<p>Hello, <em>world</em>! This is a <del>good</del>marvelous day!<br />
Here is an auto link: <a href="https://example.org/">https://example.org/</a></p>
<p>Le me introduce you to <a href="https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments">task lists</a>:</p>
<ul>
<li><input disabled="disabled" type="checkbox" /> eggs</li>
<li><input checked="checked" disabled="disabled" type="checkbox" /> milk</li>
</ul>
<p>You can also have fenced code blocks:</p>
<div class="highlight"><pre><span></span>import this
</pre></div>

py-gfmの個々の機能を一つ一つ選んで指定する場合はextensions引数にGithubFlavoredMarkdownExtensionクラスのインスタンスを指定

import markdown
from gfm import AutolinkExtension, TaskListExtension

html = markdown.markdown(source,
                         extensions=[AutolinkExtension(),
                                     TaskListExtension(max_depth=2)])

ドキュメントを適当に翻訳

ざっと、ドキュメントページを自動翻訳を使って適当に訳して整理してみると(ところどころに勝手な改ざん，蛇足を加えながら)

原文

py-gfm documentation — py-gfm 0.1.2 documentation

利用可能なextensions

gfm.autolink - URLをリンクに変換する
gfm.automail - メールアドレスをリンクに変換する
gfm.hidden_hilite - hiliteされないFenced code blocks
gfm.semi_sane_lists - GitHubライクなリスト解析
gfm.spaced_link - 任意の空白のあるリンク
gfm.strikethrough - ストライクスルーサポート
gfm.tasklist - タスクリストのサポート

モジュール

gfm - GitHub-Flavored Markdownのベースモジュール
mdx_gfm - GFMの完全な拡張(comments, issues)
mdx_partial_gfm - GFMの部分的extension（README、wiki）

サポートされている機能

Fenced code blocks
リテラル改行
Tables
ハイパーリンクの解析（http、https、ftp、emailおよび wwwサブドメイン）
Code highlighting（ダミー、現実の構文上の色付けはそのままではありません）
分離のない混合スタイルのリスト
空白を含むリンクと画像
Strikethrough(打ち間違い)
タスクリスト

サポートされていない機能

この実装は、すべてのGFM機能をサポートしているわけではありません。

設計上

コミット、問題、プルリクエスト、ユーザープロファイルへのリンク：これはアプリケーション固有のものです。提供されたクラスをサブクラス化して、独自のロジックを実装してください。

計画中

Horizontal rules

HRタグに関連するなにかのextensionの事かな
- horizontal ruleの意味・用例｜英辞郎 on the WEB：アルク
Emojis
絵文字の複数形，絵文字って言葉、外国でも使えるみたいな。
- emojis／アルコムワールド
githubでは絵文字もサポートしているみたい。
- Basic writing and formatting syntax - User Documentation

gfm.autolink- URLをリンクに変換する

原文

gfm.autolink – Turn URLs into links — py-gfm 0.1.2 documentation

このgfm.autolinkモジュールは、すべての生のURLをマークアップされたリンクに変換するextensionを提供します。
これは、John Gruber（パブリックドメイン）のWeb専用URL正規表現に基づいています。
この正規表現は、GitHubのURLマッチングとかなり密接にならびたっているようです。
2つの異なるケースと認識されている。
どちらの場合でも、正規表現はGitHubの構文解析に合わせて少し修正されました：

GitHubはFTPプロトコルURLを受け入れます。
GitHubはプロトコルまたはwwwを持つURLのみを受け付けます。
一方、Gruberの正規表現は、foo.com/barのようなものを受け入れます。

典型的な使用方法

import markdown
from gfm import AutolinkExtension

print(markdown.markdown("I love this http://example.org/ check it out",
                        extensions=[AutolinkExtension()]))

実行結果

<p>I love this <a href="http://example.org/">http://example.org/</a> check it out</p>

クラス定義

class gfm.autolink.AutolinkExtension(*args, **kwargs)
    Bases: markdown.extensions.Extension

ソースコード

URLをリンクに変換する拡張機能。

メソッド

これらのメソッドExtensionの基本クラス(/Lib/site-packages/markdown/extensions/__init__.py)で定義されているので、Extensionから派生するどのクラスでも使用可能なので、原文に記述されているが以降のクラスでは省略。

getConfig(key, default='')

指定されたキーの設定または空文字を返します。

getConfigInfo()

すべての設定の説明をタプルのリストとして返します。

getConfigs()

すべての設定をdictとして返します。

setConfig(key, value)

指定した値でkeyの設定を行います。

setConfigs(items)

dictまたはタプルのリストを指定して、複数の設定を設定します。

ところで、ここでいう設定（コンフィグレーション）はなにに使われるのだろう？
Extensionクラスを継承して独自のオプション機能を含んだExtension作成した時のためにあらかじめ用意してある機能なのだろうか？

gfm.automail- 電子メールアドレスをリンクに変換する

原文

gfm.automail – Turn email addresses into links — py-gfm 0.1.2 documentation

このgfm.automailモジュールは、すべての生の電子メールアドレスをマークアップされたリンクに変換する拡張機能を提供します。

典型的な使用方法

import markdown
from gfm import AutomailExtension

print(markdown.markdown("You can mail me at foo@example.org for more info",
                        extensions=[AutomailExtension()]))

実行結果

<p>You can mail me at <a href="mailto:foo@example.org">foo@example.org</a> for more info</p>

クラス定義

class gfm.automail.AutomailExtension(*args, **kwargs)
Bases: markdown.extensions.Extension

電子メールアドレスをリンクに変換する拡張機能。

ソースコード

gfm.hidden_hilite- hiliteされないFenced code blocks

原文

gfm.hidden_hilite – Fenced code blocks with no highlighting — py-gfm 0.1.2 documentation

このgfm.hidden_hiliteモジュールでは、シンタックスハイライトや行番号を追加せずにフェンスコードブロックを使用できる拡張機能が提供されています。

典型的な使用方法

import markdown
from gfm import HiddenHiliteExtension

print(markdown.markdown("```\nimport this\nprint('foo')\n```",
                        extensions=[HiddenHiliteExtension()]))

<p><code>import this
print('foo')</code></p>

クラス定義

class gfm.hidden_hilite.HiddenHiliteExtension(*args, **kwargs)
    Bases: markdown.extensions.codehilite.CodeHiliteExtension

ソースコード

gfm.semi_sane_lists- GitHubのようなリストの解析

原文

gfm.semi_sane_lists – GitHub-like list parsing — py-gfm 0.1.2 documentation

gfm.semi_sane_listsモジュールは、GitHubと同じようにリストを扱う拡張機能を提供します。

sane_lists拡張と同様、GitHubは別のタイプの別のリストから複数の改行で区切られている場合、リストを終了するとみなします。
sane_lists拡張とは異なり、GitHubは複数の改行で区切られていないリストタイプを混在させます。

GitHubは、段落の途中から始まるリストも認識します。
これは現在この拡張機能ではサポートされていません、なぜなら、Pythonパーサーはブロックが常に複数の改行で区切られているという深遠な信念を持っているからです。

典型的な使用方法

import markdown
from gfm import SemiSaneListExtension

print(markdown.markdown("""
- eggs
- milk

1. mix
2. stew
""", extensions=[SemiSaneListExtension()]))

実行結果

<ul>
<li>eggs</li>
<li>milk</li>
</ul>
<ol>
<li>mix</li>
<li>stew</li>
</ol>

クラス定義

class gfm.semi_sane_lists.SemiSaneListExtension(*args, **kwargs)[source]
Bases: markdown.extensions.Extension

GitHubと同じようにリストを扱う拡張機能。

ソースコード

Python MarkdownにバンドルされているSane Lists extensionも参照

Sane Lists(分別のあるリスト) - 愚鈍人

gfm.spaced_link- 任意の空白のあるリンク

原文

gfm.spaced_link – Links with optional whitespace — py-gfm 0.1.2 documentation

gfm.spaced_linkモジュールは、追加の空白を含むリンクと画像をサポートする拡張機能を提供します。

GitHubのMarkdownエンジンでは、リンクや画像に、最初の括弧と2番目の括弧の間に空白（改行を含む）を含めることができます。（例えば [text] (href)）この拡張機能は、このようなサポートを追加します。

典型的な使用方法

import markdown
from gfm import SpacedLinkExtension

print(markdown.markdown("Check out [this link] (http://example.org/)!",
                        extensions=[SpacedLinkExtension()]))

実行結果

<p>Check out <a href="http://example.org/">this link</a>!</p>

クラス定義

class gfm.spaced_link.SpacedLinkExtension(args, *kwargs) Bases: markdown.extensions.Extension

追加の空白を含むリンクや画像をサポートする拡張機能。

ソースコード

gfm.strikethrough- ストライクスルー(打ち間違い)のサポート

原文

gfm.strikethrough – Strike-through support — py-gfm 0.1.2 documentation

このgfm.strikethroughモジュールは、ストライクスルーテキストのためのGitHubのような構文を提供します。
これはダブルチルダの間のテキストです： 或る ~~ストライクスルーされた~~ テキスト

典型的な使用方法

import markdown
from gfm import StrikethroughExtension

print(markdown.markdown("I ~~like~~ love you!",
                        extensions=[StrikethroughExtension()]))

実行結果

<p>I <del>like</del> love you!</p>

ページ表示

I ~~like~~ love you!

クラス定義

class gfm.strikethrough.StrikethroughExtension(*args, **kwargs)
    Bases: markdown.extensions.Extension

2つのの間でストライクスルーテキストのサポートを追加する拡張機能

ソースコード

gfm.tasklist- タスクリストのサポート

原文

gfm.tasklist – Task list support — py-gfm 0.1.2 documentation

gfm.tasklistモジュールはタスクリストのためのGitHubのようなサポートを提供します。
それらは、実際のチェックボックス入力に変換される項目の冒頭にチェックボックスのような構文を持つ通常のリストです。
ネストされたリストがサポートされています。

構文の例：

- [x] milk
- [ ] eggs
- [x] chocolate
- [ ] if possible:
    1. [ ] solve world peace
    2. [ ] solve world hunger

注意

GitHubはチェックボックスをクリックすることでMarkdownソーステキストを更新することをサポートしています。
これはMarkdownパーサーのスコープ外のサーバー側の処理を必要とするため、この拡張ではサポートされていません。

利用可能な設定オプション

名前	型	デフォルト	説明
unordered	bool	TRUE	順序付けられていないリストの解析を無効にするには、Falseに設定します。
ordered	bool	TRUE	順序付きリストの解析を無効にするには、Falseに設定します。
max_depth	integer	∞	この制限よりも深いネストされたタスクリストの解析を停止するには、正の整数に設定します。
list_attrs	dict, callable	{}	アイテムを含む<ul>要素または<ol>要素に追加される属性。
item_attrs	dict, callable	{}	チェックボックスを含む<li>要素に追加される属性。アイテムの属性を参照してください。
checkbox_attrs	dict, callable	{}	チェックボックス要素に追加される属性。チェックボックスの属性を参照してください。

リスト属性

もし、list_attrsオプションがdictなら、キーと値のペアは、<li>要素の親要素である順序付けられていないリスト<ul>，順序付きリスト<ol>の要素に適用されます。

警告

これらの属性は、リストのすべてのネストレベル、つまりルートリストとその潜在的なサブリストの両方に再帰的に適用されます。
この動作は、代わりにcallableオブジェクトを使用して制御できます（下記参照）。

list_attrsオプションがcallableなら、次のプロトタイプのような関数でなければなりません：

def function(list, depth: int) -> dict:

返されたdict項目はHTML属性としてリスト要素に適用されます。

ここで：

listは<ul>または<ol>要素
depthはリストのルートリストに対する深さ（ルートリストの深さは1です）。

注意

この機能により、ルートリストにのみ属性を適用できます。
コードサンプル：

import markdown
from gfm import TaskListExtension

def list_attr_cb(list, depth):
    if depth == 1:
        return {'class': 'tasklist'}
    return {}

tl_ext = TaskListExtension(list_attrs=list_attr_cb)

print(markdown.markdown("""
- [x] some thing
- [ ] some other
    - [ ] sub thing
    - [ ] sub other
""", extensions=[tl_ext]))

この例では、ルートリストのみがtasklistクラス属性を持ち、「サブ」アイテムを含む属性リスト属性はありません。

アイテム属性

もし、item_attrsオプションがdictなら、キーと値のペアはHTML属性として<li>要素に適用されます。

例：

item_attrs={'class': 'list-item'}

結果は：

実行結果

<li class="list-item">...</li>

もし、item_attrsオプションがcallableなら、次のプロトタイプのような関数でなければなりません：

def function(parent, element, checkbox) -> dict:

ここで：

parentは<li>の親要素
elementは<ul>要素
checkboxは生成された<input type="checkbox">要素

返されるdict項目は、チェックボックスを含む<li>要素にHTML属性として適用されます。

チェックボックスの属性

もし、checkbox_attrsオプションがdictなら、キーと値のペアはHTML属性として<input type = "checkbox">要素に適用されます。

例：

checkbox_attrs={'class': 'list-cb'}

結果は：

<li><input type="checkbox" class="list-cb"> ...</li>

もし、checkbox_attrsオプションがcallableなら、それは次のプロトタイプのような関数でなければなりません：

def function(parent, element) -> dict:

ここで：

parentは<li>の親要素
elementは<ul>要素

返されるdict項目は、HTML属性としてcheckbox要素に適用されます。

典型的な使用方法

import markdown
from gfm import TaskListExtension

print(markdown.markdown("""
- [x] milk
- [ ] eggs
- [x] chocolate
- not a checkbox
""", extensions=[TaskListExtension()]))

実行結果

<ul>
<li><input checked="checked" disabled="disabled" type="checkbox" /> milk</li>
<li><input disabled="disabled" type="checkbox" /> eggs</li>
<li><input checked="checked" disabled="disabled" type="checkbox" /> chocolate</li>
<li>not a checkbox</li>
</ul>

ページ表示

milk
eggs
chocolate
not a checkbox

クラス定義

class gfm.tasklist.TaskListExtension(*args, **kwargs)
    Bases: markdown.extensions.Extension

GitHubタスクリストをサポートする拡張機能。
順序付きリストと順序なしリストの両方がサポートされており、個別に有効化できます。
ネストされたリストがサポートされています

例：

- [x] milk
- [ ] eggs
- [x] chocolate
- [ ] if possible:
    1. [ ] solve world peace
    2. [ ] solve world hunger

ソースコード

mdx_gfm- GFMの完全な拡張(comments, issues)

原文

mdx_gfm – Full extension for GFM (comments, issues) — py-gfm 0.1.2 documentation

GitHub-Flavored Markdown（GFM）と可能な限り互換性のある拡張機能。

この拡張モジュールは、GitHubがコメントとissuesに使用する標準的なGFMとの互換性を目指しています。
コミット、リポジトリ、およびissuesへのGitHub内リンクを除いて、GFMのドキュメントに記述されているすべての拡張機能があります。

※Issuesというのは

GitHubのMarkdown形式の要点とファイル（READMEを含む）は、GFMのわずかに異なるバリエーションを使用しています。
そのためには、以下を使ってください。

mdx_partial_gfm.PartialGithubFlavoredMarkdownExtension.

クラス定義

class mdx_gfm.GithubFlavoredMarkdownExtension(*args, **kwargs)
    Bases: mdx_partial_gfm.PartialGithubFlavoredMarkdownExtension

ソースコード

mdx_partial_gfm- GFMの部分拡張（README、wiki）

原文

mdx_partial_gfm – Partial extension for GFM (READMEs, wiki) — py-gfm 0.1.2 documentation

GitHub-Flavored Markdown（GFM）と可能な限り互換性のある拡張機能。

この拡張は、GitHubがMarkdown形式の要点とファイル（READMEを含む）に使用するGFMの変形と互換性があることを目指しています。
この別バージョンは、GFMのドキュメントに記載されているすべての拡張機能を持っているようです。
以下を除いて。

段落の改行はbrタグに変換されません
コミット、リポジトリ、およびissuesへのIntra-GitHubリンクはサポートされていません。

もし、GitHubのコメントやissuesに特有の機能のサポートが必要ななら、以下を使ってください。

mdx_gfm.GithubFlavoredMarkdownExtension.

クラス定義

class mdx_partial_gfm.PartialGithubFlavoredMarkdownExtension(*args, **kwargs)
    Bases: markdown.extensions.Extension

ソースコード