ASTなにも分からないけどmdast-util-from-scrapbox作ってる

【関西Node学園 10時限目】 ASTなにも分からないけどmdast-util-from-scrapbox作ってる Github: junseinagao / Twitter: @junpai_code

自己紹介 長尾准誠 (ながおじゅんせい) 株式会社エイチームライフデザイン Webフロントエンドエンジニア ・Next.js x HasuraでBtoBtoCなサービスを開発してます ・大学卒業後、フリーランスを2年間やったのちに会社員になりました。 ・アジャイル・チームビルディングが好きです JUNSEINAGAO/@JUNPAI_CODE

最初にこれだけ言わせてください

関西NODE.JS学園 10時限目に参加するために

この会場は大阪ですが...

本日、名古屋から来ました。

本日、話したいこと

mdast-util-from-scrapboxというESM Packageを開発しています。 https://github.com/junseinagao/mdast-util-from-scrapbox mdast JUNSEINAGAO/@JUNPAI_CODE

ライブラリを開発した経験を通じて知ったことについて話したいと思います。 ・ライブラリを開発しようとした経緯について ・Node.jsでASTを使ってMarkdownを生成するには？ ・JavaScriptで実装されたAST仕様のunistについて Node.js/JavaScript成分が少なめで、すみません...! JUNSEINAGAO/@JUNPAI_CODE

mdast-util-from-scrapboxは何をするライブラリなのか？ 一言でいうと「Scrapboxのフォーマットをmdast (Markdown Abstract Syntax Tree)に変換するツール」です。 JUNSEINAGAO/@JUNPAI_CODE

Scrapboxはhelpfeel社が提供しているWikiのSaaS ・人が増えても情報設計が破綻しないように作られたUX ・文章を書き始めるコストをなるべく排除したUI ・ブラケットとインデント中心とした独自のScrapbox記法を採用している [link] and text [* decoration] JUNSEINAGAO/@JUNPAI_CODE

Scrapboxをすごい良い感じにMarkdownに変換するサイトを作りたい 経緯 ・会社にScrapboxを試験的に導入した ・試験的導入なため、Scrapboxの権限を持っていない人が大半 ・会社には既にナレッジシェアのためにMarkdownを使ったドキュメントツールが存在しているので、社内の人にScrapboxの良さを知ってもらうには、Scrapboxで行われたアクティビティをMarkdownに変えて既存のドキュメントツールの方にも投稿していかなければいけない ・今、オンラインにあるようなツールだと「一発で他のドキュメントツールに保存できるようになるフォーマットでMarkdownに変換される」コンバーターが存在しないので作りたい [link] and text [* decoration] JUNSEINAGAO/@JUNPAI_CODE

Scrapboxをチームに導入した ・Scrapboxを使うとナレッジ(知識)のマネジメントが自然と続く形で実現できることを期待して導入しました。 ・1ヶ月のトライアルもおえてきたあたりでメンバーからはかなり好評な声をいただいてる。 ・(ここらへんのことも語り足りないので、興味ある人いたらぜひ聞いてください) JUNSEINAGAO/@JUNPAI_CODE

問題発生、Scrapboxで書いた文章をMarkdownに手軽に変換する手段が必要 scrapbox-to-markdownなツールはそこそこあるけど乱立している。 JUNSEINAGAO/@JUNPAI_CODE

既存のツールだと満足に変換できるものがない Scrapboxにはheadingがないのに強調を無理矢理headingに変換していたり [link] and text [* decoration] (でも、自分たちのチームが求めている要件に沿って作っても、同じような結果になって終わりだなあ...) JUNSEINAGAO/@JUNPAI_CODE

ScrapboxのフォーマットをASTに変換して、ASTからMarkdownを生成するときに色々オプションを設定できるようにすれば柔軟な要件に対応できる！

でも、JavaScriptでASTを介してMarkdownを生成するのってどうやるの？ ASTの概念以外なにもわからない。

Syntax Tree (ST)、Abstract Syntax Tree (AST)について解説すると 抽象構文木 ようは、文章を構造化してプログラムから扱いやすいようにオブジェクトに変換したもの JUNSEINAGAO/@JUNPAI_CODE

unifiedjs/unifiedというプロジェクトがある unified unified is two things: • unified is a collective of 500+ free and open source packages that work with content as structured data (ASTs) • unified is the core package to inspect and transform content with plugins Different kinds of content can be connected together. Particularly, markdown, natural language, HTML, XML, and JavaScript are frequently used. JUNSEINAGAO/@JUNPAI_CODE

unifiedjs/unifiedというプロジェクトがある | ............................ process ............................. | | .......... parse ... | ... run ... | ... stringify .......... | +-----------+ +-----------+ +-----------+ Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output +-----------+ +-----------+ +-----------+ | X | +-----------+ | Transformers | +-----------+ JUNSEINAGAO/@JUNPAI_CODE

remarkjs/remark re mark remark is a tool that transforms markdown with plugins. These plugins can inspect and change your markup. You can use remark on the server, the client, CLIs, deno, etc. Feature highlights ☑ popular (world's most popular markdown parser) ☑ compliant (100% to CommonMark, 100% to GFM with a plugin) ☑ plugins (150+ plugins you can pick and choose from) ☑ ASTs (inspecting and changing content made easy) JUNSEINAGAO/@JUNPAI_CODE

remarkjs/remark ・例えば、人気のMarkdownパーサー/コンパイラのremarkなどもunifiedエコシステムの一部。 ・ASTに変換することで、様々な拡張構文や処理を拡張することができる。 ・remarkが人気な理由もまさにここにあった。 JUNSEINAGAO/@JUNPAI_CODE

remarkで使われているASTの仕様(Specification)は何？

syntax-tree/mdast mdast Markdown Abstract Syntax Tree. mdast is a specification for representing markdown in a syntax tree. It implements unist. It can represent several flavours of markdown, such as CommonMark and GitHub Flavored Markdown. JUNSEINAGAO/@JUNPAI_CODE

syntax-tree/mdast For example, the following markdown: **alpha** __bravo__ Yields: { type: 'paragraph', children: [ { type: 'strong', children: [{type: 'text', value: 'alpha'}] }, {type: 'text', value: ' '}, { type: 'strong', children: [{type: 'text', value: 'bravo'}] } ] } JUNSEINAGAO/@JUNPAI_CODE

syntax-tree/mdast ・求めてたやつ。 ・mdastの中身は unist らしい。unistって何？ JUNSEINAGAO/@JUNPAI_CODE

syntax-tree/unist unist Universal Syntax Tree. unist is a specification for syntax trees. It has a big ecosystem of utilities in JavaScript for working with these trees. It's implemented by several other specifications. JUNSEINAGAO/@JUNPAI_CODE

syntax-tree/unist ・つまり、mdastを実装するには、unistとmdastに沿ってオブジェクトを作れば、OK。 ・unist-builderというunistを生成するutilsパッケージもあった。 JUNSEINAGAO/@JUNPAI_CODE

syntax-tree/unist-builder
import {u} from 'unist-builder'
const tree = u('root', [
u('subtree', {id: 1}),
u('subtree', {id: 2}, [
u('node', [u('leaf', 'leaf 1'), u('leaf', 'leaf 2')]),
u('leaf', {id: 3}, 'leaf 3'),
u('void', {id: 4})
])
])
console.dir(tree, {depth: null})
JUNSEINAGAO/@JUNPAI_CODE

Scrapboxの方も調べてみると... @progfay/scrapbox-parserというScrapboxをJavaScript Objectに変換する優秀なパーサーがある (これも一種のAST) Scrapbox Parser parse Scrapbox notation to JavaScript Object JUNSEINAGAO/@JUNPAI_CODE

・つまり、Scrapbox AST -> mdast を作れば良い ・mdastを作るだけなら、unist-builderという生成utilを使ってオブジェクトを作ってだけ！ Scrapbox Text -> Scrapbox AST -> mdast -> Markdown JUNSEINAGAO/@JUNPAI_CODE

というわけでmdast-util-from-scrapboxを誠意開発中です！ mdast-util-from-scrapbox mdast utility that turns scrapbox into a syntax tree. THIS PACKAGE IS UNDER DEVELOPED!

まとめ ・unified、remarkが人気な理由はASTを活用して連携性の高いエコシステムを築いてるから ・syntax-tree/unist というJavaScriptでSyntax Treeを実装するための仕様がある ・既に大きなエコシステムが作られており、思ったよりも簡単にASTを扱える ・(Node.jsライブラリを作る環境を構築するの大変) JUNSEINAGAO/@JUNPAI_CODE

ご清聴 ありがとうございました nagaojunsei/@junapi_code