vivliostyle
Vivliostyle Flavored Markdown (VFM), a Markdown syntax optimized for book authoring. It is standardized and published for Vivliostyle and its sibling projects.
Table of contents
Install
npm install -g @vivliostyle/vfmUse
vfm --help
vfm README.md
echo "# Hello" | vfmUsage 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 A4API
npm install --save @vivliostyle/vfmimport { stringify } from '@vivliostyle/vfm';
console.log(
stringify(`
# はじめに
{Vivliostyle|ビブリオスタイル}の世界へようこそ。
`),
);This snippet will generates:
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>はじめに</title>
</head>
<body>
<h1>はじめに</h1>
<p>
<ruby>Vivliostyle<rt>ビブリオスタイル</rt></ruby
>の世界へようこそ。
</p>
</body>
</html>Options
style (default: undefined)
Set the specified value as the href attribute of <link rel="stylesheet">.
stringify('# Hello', { style: 'https://example.com/book.css' });will generates:
<!doctype html>
<html>
<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>
<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)
If true is specified, only the HTML defined in <body> is output.
stringify('# Hello', { partial: true });will generates:
<p><h1>Hello</h1></p>title (default: undefined)
Set the specified value as the text of <title>.
stringify('# Hello', { title: 'Hello' });will generates:
<!doctype html>
<html>
<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: undefined)
Set the specified value as the lang attribute of <html>.
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>hardLineBreaks (default: false)
Converts line breaks to <br>.
stringify(
`
new
line
`,
{ hardLineBreaks: true },
);will generates:
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<p>
new<br />
line
</p>
</body>
</html>disableFormatHtml (default: false)
Disable automatic HTML format. Explicitly specify true if want unformatted HTML during development or debug.
stringify(
`text`,
{ disableFormatHtml: true },
);will generates:
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<p>text</p>
</body>
</html>math (default: true)
Handles math syntax. The default value is true, which is valid.
stringify(
`$x = y$`
);will generates:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js?config=TeX-MML-AM_CHTML"></script>
</head>
<body data-math-typeset="true">
<p><span class="math inline">\(x = y\)</span></p>
</body>
</html>To explicitly disable it, specify false for this option or math: false for Markdown's Frontmatter.
stringify(
`$x = y$`,
{ math: false }
);will generates:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<p>$x = y$</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');
}readMetadata
Read metadata from Markdown frontmatter.
Useful if just want to get the metadata, Markdown parse and metadata typing (for TypeScript) are handled by the VFM side.
readMetadata(md: string, customKeys: string[]): Metadata
- params:
md:StringMarkdown text.customKeys:String[]A collection of key names to be ignored by meta processing.
- returns:
metadata:MetadataMetadata.
import { readMetadata } from '@vivliostyle/vfm'
const md = `---
id: 'my-page'
lang: 'en'
dir: 'ltr'
class: 'my-class'
title: 'Title'
vfm:
math: false
theme: 'sample.css'
---
`;
const metadata = readMetadata(md);
console.log(metadata);About Metadata details, refer to VFM's "Frontmatter" or type information of TypeScript.
About customKeys
Use this if want to add custom metadata with a third party tool.
Keys that are not defined as VFM are treated as meta. If you specify a key name in customKeys, the key and its data type will be preserved and stored in custom instead of meta.
import { readMetadata } from '@vivliostyle/vfm'
const md = `---
title: 'Title'
tags: ['foo', 'bar']
---
`;
const metadata = readMetadata(md, ['tags']);
console.log(metadata);Results:
{
title: 'title',
custom: {
tags: ['foo', 'bar']
}
}tags is stored and retained structure in custom instead of meta.
If specify a default key such as title, it will be processed as custom.
User-specified metadata
Metadata can be specified for stringify, this specification takes precedence over Frontmatter.
The following usage is assumed.
- Use metadata other than Frontmatter
- Process Frontmatter metadata obtained by
readMetadata
stringify(
'# Title',
{},
{ title: 'My Page', body: [{ name: 'id', value: 'page' }] },
);HTML:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>My Page</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body id="page">
<section id="title" class="level1">
<h1>Title</h1>
</section>
</body>
</html>Spec
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.
Links
Contribution
We want you to:
- Join Discussion to improve spec
- Implement alpha-stage specs and send a PR
- Test beta-stage features and report a bug
