search

vivliostyle / vfm

⬇️ Open and extendable Markdown syntax and toolchain.
https://vivliostyle.github.io/vfm/#/vfm
Other
72 stars 12 forks source link

☂️Spec #1

Closed uetchy closed 3 years ago

uetchy commented 4 years ago

Twitter Post - VFM

Custom Markdown syntax specialized in book authoring.

✍️Working Draft 🗣Slack

Feedback

If you have any suggestions on adding and/or modifying stuff in the working draft, please create an issue.

References

uetchy commented 4 years ago

Timeline

TBD

akabekobeko commented 4 years ago

Frontmatter

Markdown (ファイル) 単位のメタデータ定義方法として Frontmatter を提案します。

目的

記法

記法は著名な静的サイト ジェネレーターを踏襲します。

これらは Markdown の先頭へ主に YAML 形式 (Hugo は +++ で定義すると TOML になる) で記述します。

---
property: value
---

プロパティーについては以下を提案します。草案なので最小です。

Property Type Description
title String Markdown 文書のタイトル。Markdown 先頭の # をタイトルにする方法も考えられるが、必ずしもこれが定義されるとは限らないので明示的なタイトルがほしい。
author String 著者。
akabekobeko commented 4 years ago

For english:

Frontmatter

Propose Frontmatter as a method of defining metadata in Markdown (file) units.

Purpose

Format

The format follows the famous static site generator.

These are written at the top of Markdown mainly in YAML format (Hugo becomes TOML when defined with +++).

---
property: value
---

For properties, we suggest the following: Minimal because it is a draft.

Property Type Description
title String Markdown The title of the document. Markdown The first # can be a title, but this is not always defined, so I want an explicit title.
author String Author.
akabekobeko commented 4 years ago

基本書式と拡張書式

Markdown の HTML 変換定義において GFM(GitHub Flavored Markdown) など広く普及した書式を参考にするなら、それを基本書式として明示することを提案します。これは既存の書式へ基づく場合の提案です。そうした対象がなければ不要です。

目的

基本書式に対して機能拡張したものについては、拡張書式として扱うことを提案します。VFM の書式リファレンスを公開する際、ユーザーが基本と拡張を区別できることが好ましいです。

基本書式が明示されることで、少なくともその範疇であれば互換や可搬性が保証されることになります。これは他の Markdown 書式との相互変換や移行にも役立つでしょう。

akabekobeko commented 4 years ago

For english:

Basic format and extended format

If refer to a widely used format such as GFM (GitHub Flavored Markdown) in the HTML conversion definition of Markdown, it is suggested to specify it as a basic format. This is a suggestion based on existing formats. It is unnecessary if there is no such object.

Purpose

It is proposed that the extension of the basic format be treated as an extended format. When publishing a VFM format reference, it is desirable for users to be able to distinguish between basic and extended.

Specifying the basic format guarantees compatibility and portability, at least in that category. This will also help with conversion and migration to and from other Markdown formats.

uetchy commented 4 years ago

If refer to a widely used format such as GFM (GitHub Flavored Markdown) in the HTML conversion definition of Markdown, it is suggested to specify it as a basic format. This is a suggestion based on existing formats. It is unnecessary if there is no such object.

VFM doesn't intend to be a superset/subset of either CommonMark or GFM because of the fundamental incompatibility with a passage handling. Rather, VFM will be a self-contained specification that derives only some of the syntax from other dialects in which is required for book writing.

akabekobeko commented 4 years ago

他の書式を引用しなくても、よく使われる書式をそこそこ網羅したサンプルさえあれば「だいたい GFM や CommonMark のようだ」と判断してくれそうですね。

Even if don't quote other formats, it seems that if you have a sample that covers all of the commonly used formats, it will judge that it is "generally like GFM or CommonMark".

MurakamiShinyu commented 4 years ago

Pandoc's Markdown

Pandoc’s Markdown has some useful features and we should consider adopting them:

MurakamiShinyu commented 4 years ago

でんでんマークダウン

(Denden Markdown)

https://conv.denshochan.com/markdown

でんでんマークダウンの記法は Markdown の方言のひとつ PHP Markdown Extra をさらに拡張して、日本語と電子出版に最適化させたものです。

(The Denden Markdown notation is a further extension of PHP Markdown Extra, a Markdown dialect, optimized for Japanese and electronic publishing.)

でんでんマークダウンはとても参考になると思います。日本語に必要なルビや縦中横など：

ただしこの縦中横の記法（例: 昭和^53^年）は、他のMarkdown拡張（pandocなど）では上付き文字（superscript）だったりするので、ほかの記法に変えた方がよいかもしれません。

uetchy commented 4 years ago

Thanks for the feedback and ideas! After a few days, I realized that each suggestion must be separated into a single issue so that we can comment on it directly and can maintain the authorship.

If you have any suggestions on adding and/or modifying stuff in the working draft, please create an issue.

uetchy commented 4 years ago

vfm just hit alpha.10. Alpha package is available at next channel in npm.

npm i -g @vivliostyle/vfm@next
npm i -g @vivliostyle/vfm@1.0.0-alpha.10

vfm@next supports beta specs which are needed to be tested well.

Comments & PRs are welcome!

akabekobeko commented 3 years ago

@uetchy さんのコメントで各案を個別の issue にしようと提案されており、既にそう運用されているため本件は close します。