The vfm from akabekobeko

Vivliostyle Flavored Markdown (VFM), a Markdown syntax optimized for book authoring. It is standardized and published for Vivliostyle and its sibling projects.

Install
Use
- Usage with vivliostyle command
API
- Options
- Advanced usage
  - Unified processor
  - Unified plugin
Spec
- Principles
- Links
Contribution
- Maintainers

Install

npm install -g @vivliostyle/vfm

If you want to test latest spec, run npm install -g @vivliostyle/vfm@next instead.

Use

vfm --help
vfm README.md
echo "# Hello" | vfm

Usage with `vivliostyle` command

npm i -g @vivliostyle/cli
vfm README.md --style https://raw.githubusercontent.com/jagat-xpub/cosmology/gh-pages/css/scholarly.css > book.html
vivliostyle build book.html -s A4

API

npm install --save @vivliostyle/vfm
# or
yarn add @vivliostyle/vfm

const { stringify } = require('@vivliostyle/vfm');

console.log(
  stringify(`
# はじめに

{Vivliostyle|ビブリオスタイル}の世界へようこそ。
`),
);

This snippet will generates:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <h1>はじめに</h1>
    <p>
      <ruby>Vivliostyle<rt>ビブリオスタイル</rt></ruby
      >の世界へようこそ。
    </p>
  </body>
</html>

Options

`style` (default: `undefined`)

stringify('# Hello', { style: 'https://example.com/book.css' });

will generates:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="https://example.com/book.css" />
  </head>
  <body>
    <p><h1>Hello</h1></p>
  </body>
</html>

style can be an array of styles.

stringify('# Hello', {
  style: ['https://example.com/book.css', 'https://example.com/extra.css'],
});

will generates:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="https://example.com/book.css" />
    <link rel="stylesheet" href="https://example.com/extra.css" />
  </head>
  <body>
    <p><h1>Hello</h1></p>
  </body>
</html>

`partial` (default: `false`)

stringify('# Hello', { partial: true });

will generates:

<p><h1>Hello</h1></p>

`title` (default: `undefined`)

stringify('# Hello', { title: 'Hello' });

will generates:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hello</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <p><h1>Hello</h1></p>
  </body>
</html>

`language` (default: `en`)

stringify('# Hello', { language: 'ja' });

will generates:

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <p><h1>Hello</h1></p>
  </body>
</html>

Advanced usage

Unified processor

import { VFM } from '@vivliostyle/vfm';

const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();

Unified plugin

import unified from 'unified';
import vfm from '@vivliostyle/vfm/lib/revive-parse';
import html from '@vivliostyle/vfm/lib/revive-rehype';

function main() {
  unified()
    .use(vfm)
    .use(customRemarkPlugin)
    .use(html)
    .use(customRehypePlugin)
    .processSync('# Hello');
}

Spec

Current Status

Principles

Open: steadily improving through open discussion and feedback from the vast community.
Consistent: Provides reference implementation for parsing and converting VFM to HTML, allowing other non Vivliostyle projects to use this syntax for their purposes.