nikkie-ftnextの日記

イベントレポートや読書メモを発信

Markdownの原稿をSphinxで変換して作ったHTMLの中の外部リンクも、sphinx-new-tab-link を使ってブラウザの新しいタブで開けることを確認しました

Sphinx

はじめに

聞いて聞いて！ nikkieです。

ドキュメント変換ツールSphinxはサードパーティのMyST-Parser拡張を使うと、Markdownファイルからドキュメント（HTMLやPDFなどなど）を作れます。
Markdownからドキュメントを作るときに、私が開発したライブラリsphinx-new-tab-linkが一緒に使えるのか検証しました1。

目次

結論：MyST-Parserとsphinx-new-tab-linkは一緒に使えます！

百聞は一見に如かず、sphinx-new-tab-linkのガイド中のMarkdownの例を実際にご覧ください。

MyST-Parserとsphinx-new-tab-linkを一緒に使う設定

$ pip install sphinx-new-tab-link myst-parser

conf.py2

extensions = [
    "myst_parser",
    "sphinx_new_tab_link",
]

これだけです！！

Markdownの例の裏側

ガイドのMarkdownの例の元は、以下のようなMarkdownファイルです3。

# Markdown example / Markdownの例

## Links / リンク集

* PyPI <https://pypi.org/project/sphinx-new-tab-link/>
* [GitHub Repository](https://github.com/ftnext/sphinx-new-tab-link)

MyST-Parserとは

このブログで何度もお世話になっている『Sphinxをはじめよう』。
付録D「Markdownで書いてみよう」でMyST-Parserが紹介されます。

Markdownは実は仕様が曖昧で、ツールによって記法の種類が異なるそうです（ref: 書籍のD.1）。
たしかにGitHub Flavored Markdown（GFM）などMarkdownの拡張の存在を聞いたことがあります。

この問題に対処するためにCommonMarkプロジェクトが立ち上がり、仕様がまとまってきているそうです。
そしてMyST-Parserは、CommonMark仕様のMarkdownをサポートするSphinx拡張4です（ref: 書籍のD.2）。

MyST-Parserがサポートするリンクの書き方には3通りある

MyST-Parserがサポートする（CommonMarkの）リンクの記法は3通りあります。
2. CommonMarkより

  • Autolink
  • URL Link
  • Reference LinkとLink Definition

6.1. CommonMark link format で追加の解説がされます。

URLを<>で囲むとリンクになります。

PyPI <https://pypi.org/project/sphinx-new-tab-link/>

リンクのテキストを指定できる書き方です。

[GitHub Repository](https://github.com/ftnext/sphinx-new-tab-link)

Link Definitionでリンクを定義します。

[guide-ja]: https://ftnext.github.io/sphinx-new-tab-link/guide.html

定義したリンクはドキュメントの中で複数回使えるそうです（Reference Link）！

[公開版ガイド(ja)][guide-ja] 

例もある [日本語版ガイド][guide-ja] をぜひどうぞ！

これはreSTの「ハイパーリンクターゲット5」と似ていると思いました。

外部リンクがsphinx-new-tab-linkによりブラウザの新しいタブで開きます！

6.2. Default destination resolutionによると、リンクの行き先には以下の2種類があります。

  • external target
    • Sphinxプロジェクトの外部（external）という理解です
  • internal target
    • Sphinxプロジェクトの内部（internal）という理解です

sphinx-new-tab-linkは外部リンクをブラウザの別のタブで開くように実装しています。
そしてMarkdownのリンク記法で外部リンクとなるのは以下です（6.2で示されるルールの箇条書きより）

  • Autolink6
  • 行き先がhttp:, https:, ftp:, またはmailto:のリンク7

まとめると、Markdown（CommonMark）のAutolinkや、スキーマから指定したURL linkやReference Linkが外部リンクです。
sphinx-new-tab-linkにより、ビルドしたHTMLでこれらのリンクはブラウザの新しいタブで開きます！

終わりに

SphinxでMarkdownをビルドしてできるHTMLでもsphinx-new-tab-linkが機能することが確認できました🙌
「自分は絶対に使う！」（だから作って公開した）ライブラリなのですが、Sphinxエコシステムの中で他の拡張によって可能性が広がり、とてもワクワクしています。

4月のPyCon USのポスター発表8でもいろんな方に知ってもらえるといいなあ〜

📣「この記事でsphinx-new-tab-linkを知ったよ」という方、ぜひぜひ試していただき、ちょっとしたことでもかまいませんので、（伸びしろだけでなくぜひぜひよい点も）フィードバックをお寄せください！

私、アスタリスクが好きなんですが、スター🌟をいただいても嬉しいです！

  1. リリース報告エントリで書いた次を回収しました！「「Markdownサポートしているなら使うよ」って方はいそうなので、次はMarkdownサポートかなと思っています。」（終わりに）↩
  2. https://github.com/ftnext/sphinx-new-tab-link/blob/ad7468f698bcbf15097cf408f915eb6efb26a726/docs/conf.py#L21-L26↩
  3. https://raw.githubusercontent.com/ftnext/sphinx-new-tab-link/ad7468f698bcbf15097cf408f915eb6efb26a726/docs/markdown-example.md↩
  4. MyST-ParserはリポジトリにSphinx拡張と同時にCommonMark互換の拡張パーサも含むそうです（It contains an extended CommonMark-compliant parser using markdown-it-py, as well as a Sphinx extension that allows you to write MyST Markdown in Sphinx. READMEより）↩
  5. reStructuredTextとリンクを作るマークアップ（全部一緒だと思っていたのですが、細かい意味の違いがあった…だと…） - nikkie-ftnextの日記↩
  6. 6.1にありますが、AutolinkにはURLのスキーム（httpsの部分）が必要です↩
  7. 6.2より「Destinations beginning with http:, https:, ftp:, or mailto: will be treated as external URL links.」↩
  8. 4月のPyCon US 2023にposter sessionしに行きます！！ #PyConUS - nikkie-ftnextの日記↩