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
930
mdbookのプラグインを作る話
puripuri2100
February 25, 2021
Tweet
Share
More Decks by puripuri2100
See All by puripuri2100
法律文書の自動解析2024
puripuri2100
0
27
絵文字は構文解析できるのか
puripuri2100
0
65
係り受け解析を用いた法律文書中の略称規定の解析についての報告
puripuri2100
0
2.8k
気胸の胸部CTデータの可視化
puripuri2100
0
280
SATySFiで作成する構文解析器
puripuri2100
0
250
SATySFiの開発についての要望
puripuri2100
0
410
研究の場においてのRust 製ソフトウェアのバージョン管理について
puripuri2100
0
590
法律文書の自動解析
puripuri2100
1
860
汎用的なコードフォーマットライブラリの作成
puripuri2100
0
300
Other Decks in Technology
See All in Technology
【PHPカンファレンス 2025】PHPを愛するひとに伝えたい PHPとキャリアの話
tenshoku_draft
0
120
TechLION vol.41~MySQLユーザ会のほうから来ました / techlion41_mysql
sakaik
0
190
エンジニア向け技術スタック情報
kauche
1
270
Observability infrastructure behind the trillion-messages scale Kafka platform
lycorptech_jp
PRO
0
140
フィンテック養成勉強会#54
finengine
0
180
Node-REDのFunctionノードでMCPサーバーの実装を試してみた / Node-RED × MCP 勉強会 vol.1
you
PRO
0
120
標準技術と独自システムで作る「つらくない」SaaS アカウント管理 / Effortless SaaS Account Management with Standard Technologies & Custom Systems
yuyatakeyama
3
1.3k
20250625 Snowflake Summit 2025活用事例 レポート / Nowcast Snowflake Summit 2025 Case Study Report
kkuv
1
310
Amazon Bedrockで実現する 新たな学習体験
kzkmaeda
2
580
低レイヤを知りたいPHPerのためのCコンパイラ作成入門 完全版 / Building a C Compiler for PHPers Who Want to Dive into Low-Level Programming - Expanded
tomzoh
4
3.2k
マーケットプレイス版Oracle WebCenter Content For OCI
oracle4engineer
PRO
3
900
Understanding_Thread_Tuning_for_Inference_Servers_of_Deep_Models.pdf
lycorptech_jp
PRO
0
130
Featured
See All Featured
Java REST API Framework Comparison - PWX 2021
mraible
31
8.6k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
7
700
Writing Fast Ruby
sferik
628
61k
Optimising Largest Contentful Paint
csswizardry
37
3.3k
Why You Should Never Use an ORM
jnunemaker
PRO
57
9.4k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
331
22k
Building an army of robots
kneath
306
45k
The Invisible Side of Design
smashingmag
300
51k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
124
52k
Into the Great Unknown - MozCon
thekraken
39
1.9k
Agile that works and the tools we love
rasmusluckow
329
21k
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
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