Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
mdbookのプラグインを作る話
Search
puripuri2100
February 25, 2021
Technology
0
820
mdbookのプラグインを作る話
puripuri2100
February 25, 2021
Tweet
Share
More Decks by puripuri2100
See All by puripuri2100
絵文字は構文解析できるのか
puripuri2100
0
28
係り受け解析を用いた法律文書中の略称規定の解析についての報告
puripuri2100
0
1.9k
気胸の胸部CTデータの可視化
puripuri2100
0
230
SATySFiで作成する構文解析器
puripuri2100
0
190
SATySFiの開発についての要望
puripuri2100
0
370
研究の場においてのRust 製ソフトウェアのバージョン管理について
puripuri2100
0
520
法律文書の自動解析
puripuri2100
1
620
汎用的なコードフォーマットライブラリの作成
puripuri2100
0
280
ユーザーがカスタマイズできるクラスファイル ―v0.0.x と v0.1.x それぞれでの実装 ―
puripuri2100
0
310
Other Decks in Technology
See All in Technology
これまでの計測・開発・デプロイ方法全部見せます! / Findy ISUCON 2024-11-14
tohutohu
3
360
OCI Network Firewall 概要
oracle4engineer
PRO
0
4.1k
AIチャットボット開発への生成AI活用
ryomrt
0
170
Microsoft MVPになる前、なってから/Fukuoka_Tech_Women_Community_1_baba
nina01
0
190
Python(PYNQ)がテーマのAMD主催のFPGAコンテストに参加してきた
iotengineer22
0
460
Platform Engineering for Software Developers and Architects
syntasso
1
510
フルカイテン株式会社 採用資料
fullkaiten
0
40k
Evangelismo técnico: ¿qué, cómo y por qué?
trishagee
0
350
隣接領域をBeyondするFinatextのエンジニア組織設計 / beyond-engineering-areas
stajima
1
270
Terraform Stacks入門 #HashiTalks
msato
0
350
OCI Vault 概要
oracle4engineer
PRO
0
9.7k
マルチモーダル / AI Agent / LLMOps 3つの技術トレンドで理解するLLMの今後の展望
hirosatogamo
37
12k
Featured
See All Featured
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
44
2.2k
GraphQLとの向き合い方2022年版
quramy
43
13k
A designer walks into a library…
pauljervisheath
203
24k
Agile that works and the tools we love
rasmusluckow
327
21k
5 minutes of I Can Smell Your CMS
philhawksworth
202
19k
Why Our Code Smells
bkeepers
PRO
334
57k
Refactoring Trust on Your Teams (GOTO; Chicago 2020)
rmw
31
2.7k
Six Lessons from altMBA
skipperchong
27
3.5k
Optimizing for Happiness
mojombo
376
70k
A Philosophy of Restraint
colly
203
16k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
159
15k
The Power of CSS Pseudo Elements
geoffreycrofte
73
5.3k
Transcript
mdbook のプラグインを作る話 Rust LT 会 @puripuri2100 2021/2/25
自己紹介 所属 開成学園開成高等学校 学年 高校二年 普段やってること SAT YSFIのパッケージ作成・Rust でのパーサー の作成など
twitter @puripuri2100 GitHub @puripuri2100 e-mail
[email protected]
1
mdbook とは Rust 界隈で大きめの文書を作るときに頻繁に使われるツール (rust-lang 公式がメンテしている) 。 ファイルの path と文章構造を対応させた
SUMMARY ファイルを 基に、markdown ファイル群を HTML ファイル群に変換するソフ トウェア。 詳しい使い方は公式ドキュメントの https://rust-lang.github.io/mdBook/index.html を読みましょう。 2
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 book.tomlに書く設定によってどちらで呼び出すのか指定できる。
[preprocessor.<name>]と書くとプリプロセッサを呼び出し、 [output.<name>]と書くと代替バックエンドを呼び出す。 3
mdbook のプラグインについて mdbook-<name>というソフトウェアを用意しておくと、mdbook を 起動したときに自動で実行される。 プラグインにはプリプロセッサと代替バックエンドの 2 種類が ある。 book.tomlに書く設定によってどちらで呼び出すのか指定できる。
[preprocessor.<name>]と書くとプリプロセッサを呼び出し、 [output.<name>]と書くと代替バックエンドを呼び出す。 今回自分が作ったのは、 「markdown ファイルから SAT YSFIのド キュメントファイルを生成する」代替バックエンド。 https://github.com/puripuri2100/mdbook-satysfi 3
代替バックエンドの作り方 stdinから JSON 形式で設定などが与えられるので、mdbook のラ イブラリの方で提供されている RenderContext::from_jsonという関 数を用いることでデータ構造に自動で直してくれる。 4
代替バックエンドの作り方 stdinから JSON 形式で設定などが与えられるので、mdbook のラ イブラリの方で提供されている RenderContext::from_jsonという関 数を用いることでデータ構造に自動で直してくれる。得られる データの種類: •
book.tomlに書いてあるものを toml::Value構造にしたもの • 現在位置や生成先の PathBuf • SUMMARY.mdの中の文章構造と、それに対応するファイルの中身 • タイトルや著者名などの book に関するデータ • build 時に使う設定(指定されたファイルが存在しない場合 に自動生成するかしないか、など) • 埋め込む Rust のコードの Edition が何か、という情報 4
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 5
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 1. markdown ファイルの中身が既に得られている← path を 使ってファイル先を読みにいかなくて良い
5
ハマりどころその 1 基本的には得られるデータを上手いこと弄って変換して出力すれ ば作れるが、ハマったところがあるので紹介 1. markdown ファイルの中身が既に得られている← path を 使ってファイル先を読みにいかなくて良い
2. data.book.iter()でファイル構造を iterator にできるので、わ ざわざ再帰関数を書く必要はない 5
テキストを出力したい形式に変換する markdown テキストを解析するのには pulldown-cmarkクレートを 用いるのが良い mdbook 本体も使用していて解析結果を統一できるうえに、かな り解析が早く、タグの場合分けによって出力結果を切り変えるの が楽 6
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない <!-- <p> hoge --> <span style="background-color: #0099FF" class="foo">fuga</spam> 7
ハマりどころその 2 markdown に埋め込まれた HTML コードの解析がとてつもなく 大変 基本的に HTML のコードかどうかは「1
行単位」でしか教えてく れない <!-- <p> hoge --> <span style="background-color: #0099FF" class="foo">fuga</spam> コメントの中の HTML タグへの対処や、途中で改行されている HTML タグへの対処などは、正規表現を使って場合分けをしたり、 現在の状態を変化させながら場合分けをしたりする必要があって かなり大変 7
ハマりどころその 2(解決策) markdown に埋め込まれた HTML コードごと HTML コードに変換 して、変換後のコードを解析すれば楽になる! 8
ハマりどころその 2(解決策) markdown に埋め込まれた HTML コードごと HTML コードに変換 して、変換後のコードを解析すれば楽になる! ただし、&が&になり、<が<に、>が>に自動で変換されて
いるので、replaceメソッドを使って置き換える必要がある 8
ハマりどころ 3 ソースコード挿入に関して mdbook 独自拡張が存在する1ので、 なんとかしないといけない 1https://rust-lang.github.io/mdBook/format/mdbook.html 9
ハマりどころ 3 ソースコード挿入に関して mdbook 独自拡張が存在する1ので、 なんとかしないといけない {{#include file.rs}}のようにすると file.rsを読み込むような拡 張に
関しては、手書きパーサーで頑張りました(力技) 将来的にはここら辺を簡単に処理してくれる関数を公式が提供し てくれると嬉しいですね 1https://rust-lang.github.io/mdBook/format/mdbook.html 9
まとめ • book を作るのに良く使う mdbook には拡張機能を自分で作 る機能がある • 公式ライブラリ提供の関数を使えば作成者は変換プロセスだ けに集中できる
• ハマりどころがいくつかある • HTML コードへの対処がかなり難しいので、一旦全部 HTML コードに変換するのがオススメ • mdbook の独自拡張については結構頑張る必要がある 10