vivliostyle/vfm

readMetadata の引数と Metadata プロパティーの excludes を別の名前にする

akabekobeko opened this issue · 4 comments

akabekobeko commented

refs: #141

Frontmatter で未定義のキーを meta として処理せず、YAML 解析結果のデータ構造を維持する目的で excludes という引数を追加した。meta 処理からの除外という意味で excludes と命名したが、実際の用途としてはサードパーティー製ツール独自のキーを定義するためのものである。

よって除外というより独自とかユーザー (サードパーティー) であることを示す名前のほうがよいだろう。例えば customizeKey や userKeys など。Metdata のプロパティーも同様。

既に VFM v1.2.0 として excludes が反映されたものをリリースしたが、現時点ならこれを利用する API ユーザーはほとんどいないと思われるので今の内に改名したい。Metadata プロパティーについてはインターフェースとして影響がある。

akabekobeko commented

@MurakamiShinyu
#141 の村上さん案を取り入れて実装しましたが、↑のとおり命名を深く考えず実装してしまいました。実際に vivliostyle-sitegen から利用しようとして excludes では意味が分かりにくいと気づき、名称変更を検討しています。

現在は

readMetadata(md: string, excludes: string[]): Metadata

type Metadata = {
  excludes?: {
    [key: string]: any;
  }
}

となっています。この excludes を customizeKeys か userKeys に変更したいと考えています。これらのどちらか、またはよりよい名前などがあれば意見をください。

MurakamiShinyu commented

custom でどうでしょう。type Metadata = {} のプロパティ名は custom で、readMetadata() の引数名としては customKeys かな。

これで指定したキーはたとえば lang や title などであっても、HTMLにlangやtitleとしては出力しないことになるという理解でよいですね？

  • 👍1
akabekobeko commented

ありがとうございます。引数としては YAML のキーを指しますが処理結果はプロパティー内にキーと値をまとめて格納してるので Keys なしのほうが分かりやすいですね。

これで指定したキーはたとえば lang や title などであっても、HTMLにlangやtitleとしては出力しないことになるという理解でよいですね？

はい。標準のキーを指定した場合は通常の処理をスキップして custom へ格納されることになります。この挙動のテストコードでは非サポートとコメントしましたが、標準キーを独自処理する目的で利用されるかもしれませんので、README.md に解説してもよさそうですね。

  • 👍1
akabekobeko commented

@MurakamiShinyu
#144 のレビュー、ありがとうございました！merge して VFM v1.2.1 へ反映させたので本件は close します。