### Setup Development Environment
Source: https://github.com/vivliostyle/vfm/blob/main/CONTRIBUTING.md
Clone the repository, install dependencies, build the project, and link it locally. Use `npm run dev` for continuous development.
```bash
git clone https://github.com/vivliostyle/vfm.git && cd vfm
npm install
npm run build
npm link
DEBUG=vfm vfm
```
--------------------------------
### Run ESM Example
Source: https://github.com/vivliostyle/vfm/blob/main/examples/esm/README.md
Execute the example using npm start to see VFM render Markdown to HTML. Ensure VFM is installed as a local package.
```shell
$ npm start
> vfm-esm@1.0.0 start
> node src/index.js
Hello, VFM!
Hello, VFM!
This is a simple example of using VFM to render Markdown to HTML.
```
--------------------------------
### Install and Use VFM CLI
Source: https://context7.com/vivliostyle/vfm/llms.txt
Install the VFM CLI globally and use it to convert Markdown files to HTML, pipe content from stdin, or apply stylesheets and build with Vivliostyle.
```bash
# Install globally
npm install -g @vivliostyle/vfm
# Convert a file
vfm input.md > output.html
# Pipe from stdin
echo "# Hello" | vfm
# Apply a stylesheet and build with Vivliostyle
vfm README.md --style https://example.com/book.css > book.html
vivliostyle build book.html -s A4
# All CLI flags
vfm input.md \
--style https://example.com/book.css \
--style https://example.com/extra.css \
--partial \
--title "My Book" \
--language ja \
--hard-line-breaks \
--disable-format-html \
--disable-math \
--img-figcaption-order figcaption-img \
--assign-id-to-figcaption \
--footnote pandoc
```
--------------------------------
### Install VFM CLI
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Install the Vivliostyle Flavored Markdown processor globally using npm.
```bash
npm install -g @vivliostyle/vfm
```
--------------------------------
### Install VFM Package
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Install the @vivliostyle/vfm package as a dependency for use in your project.
```bash
npm install --save @vivliostyle/vfm
```
--------------------------------
### Use VFM CLI
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Basic usage examples for the VFM command-line interface, including help, file processing, and piping input.
```bash
vfm --help
vfm README.md
echo "# Hello" | vfm
```
--------------------------------
### Initialize Docute with VFM Configuration
Source: https://github.com/vivliostyle/vfm/blob/main/docs/index.html
Configure Docute for VFM, including navigation, sidebar, and language overrides. This setup is useful for creating documentation sites with custom structures.
```javascript
if (location.hash.indexOf('%23')) { // fix %-encoded '#' in hash location.hash = location.hash.replace('%23', '#'); } new Docute({
title: 'VFM: Vivliostyle Flavored Markdown',
target: '#docute',
plugins: [],
nav: [
{
title: 'Home',
link: '/',
},
{
title: 'Vivliostyle',
link: 'https://vivliostyle.org',
},
{
title: 'GitHub',
link: 'https://github.com/vivliostyle/vfm',
},
],
sidebar: [
{
title: 'Spec',
children: [
{
title: 'VFM',
link: '/vfm'
},
{
title: 'Hooks',
link: '/hooks'
},
{
title: 'Theme Spec',
link: 'https://vivliostyle.github.io/themes/#/spec'
},
]
},
{
title: 'Community',
children: [
{
title: 'GitHub',
link: 'https://github.com/vivliostyle'
},
{
title: 'Twitter',
link: 'https://twitter.com/vivliostyle'
},
{
title: 'Slack',
link: 'https://join.slack.com/t/vivliostyle/shared_invite/enQtNzc1NjE4ODk1ODI5LWQxZjM4YTZjMmQ0ZTUyNmUyOGZlMzIwZjQ5OWYwYjkyZDZmOTIwNGMwOWU5NDc0NjE5OTAyMmVhZTRhYTAyNWQ'
},
]
},
],
overrides: {
'/': {
language: 'English',
},
'/ja/': {
language: 'Japanese',
nav: [
{
title: 'ホーム',
link: '/ja/'
},
{
title: 'Vivliostyle',
link: 'https://vivliostyle.org/ja/'
},
{
title: 'GitHub',
link: 'https://github.com/vivliostyle/vfm'
},
],
sidebar: [
{
title: 'Spec',
children: [
{
title: 'VFM',
link: '/ja/vfm'
},
{
title: 'Hooks',
link: '/ja/hooks'
},
{
title: 'Theme Spec',
link: 'https://vivliostyle.github.io/themes/#/ja/spec'
},
]
},
{
title: 'Community',
children: [
{
title: 'GitHub',
link: 'https://github.com/vivliostyle'
},
{
title: 'Twitter',
link: 'https://twitter.com/vivliostyle'
},
{
title: 'Slack',
link: 'https://join.slack.com/t/vivliostyle/shared_invite/enQtNzc1NjE4ODk1ODI5LWQxZjM4YTZjMmQ0ZTUyNmUyOGZlMzIwZjQ5OWYwYjkyZDZmOTIwNGMwOWU5NDc0NjE5OTAyMmVhZTRhYTAyNWQ'
},
]
},
]
}
}
});
```
--------------------------------
### HTML Output for Frontmatter Priority
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
The resulting HTML for the frontmatter priority example, showing that the 'id' from the root frontmatter ('sample1') is used.
```html
```
--------------------------------
### Enable Math Syntax in VFM
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Math syntax is enabled by default. This example shows the default usage.
```javascript
stringify(
`$x = y$`
);
```
--------------------------------
### Class Property Merging Example
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
Demonstrates how 'class' properties from the root, html, and body frontmatter are merged with spaces in between.
```yaml
---
class: 'root'
html:
class: 'html'
body:
class: 'body sample'
---
```
--------------------------------
### Frontmatter Priority Example
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
Illustrates the priority of frontmatter definitions when duplicate properties exist, such as 'id' in the root and 'html' properties. The root definition takes precedence.
```yaml
---
id: 'sample1'
html:
id: 'sample2'
---
```
--------------------------------
### VFM Frontmatter Example
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
Demonstrates how to define various metadata properties in YAML frontmatter for VFM processing. This includes attributes for html, body, base, meta, link, script, and VFM-specific settings.
```yaml
---
id: 'my-page'
lang: 'ja'
dir: 'ltr'
class: 'my-class'
title: 'Title'
html:
data-color-mode: 'dark'
data-light-theme: 'light'
data-dark-theme: 'dark'
body:
id: 'body'
class: 'foo bar'
base:
target: '_top'
href: 'https://www.example.com/'
meta:
- name: 'theme-color'
media: '(prefers-color-scheme: light)'
content: 'red'
- name: 'theme-color'
media: '(prefers-color-scheme: dark)'
content: 'darkred'
link:
- rel: 'stylesheet'
href: 'sample1.css'
- rel: 'stylesheet'
href: 'sample2.css'
script:
- type: 'text/javascript'
src: 'sample1.js'
- type: 'text/javascript'
src: 'sample2.js'
vfm:
math: false
theme: 'theme.css'
partial: false
hardLineBreaks: false
disableFormatHtml: false
author: 'Author'
---
Text
```
--------------------------------
### Enter Pre-release
Source: https://github.com/vivliostyle/vfm/blob/main/CONTRIBUTING.md
Initiate a pre-release version using release-it, tagging it as 'beta' and 'next' for npm.
```bash
release-it --preRelease=beta --npm.tag=next
```
--------------------------------
### VFM(options?, metadata?)
Source: https://context7.com/vivliostyle/vfm/llms.txt
Creates and returns a reusable [unified](https://github.com/unifiedjs/unified) `Processor` instance with the full VFM remark+rehype pipeline configured. Use this when you need to call `.processSync()` multiple times, inspect ASTs, or integrate with other unified plugins.
```APIDOC
## VFM(options?, metadata?)
### Description
Creates and returns a reusable [unified](https://github.com/unifiedjs/unified) `Processor` instance with the full VFM remark+rehype pipeline configured. Use this when you need to call `.processSync()` multiple times, inspect ASTs, or integrate with other unified plugins.
### Parameters
#### options
- **options** (object) - Optional - Configuration options for the VFM processor.
- **partial** (boolean) - Optional - If true, the processor will output only the `` fragment.
- **editPlugins** (function) - Optional - A function to modify the built-in plugin list before execution. It receives an object with `mdastPlugins` and `hastPlugins` and should return a modified object.
#### metadata
- **metadata** (object) - Optional - User-specified metadata to override frontmatter values.
### Request Example
```js
import { VFM } from '@vivliostyle/vfm';
import unified from 'unified';
import vfmParse from '@vivliostyle/vfm/lib/revive-parse';
import vfmHtml from '@vivliostyle/vfm/lib/revive-rehype';
// Simple reusable processor
const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();
// Custom unified pipeline
function customPipeline() {
unified()
.use(vfmParse)
.use(myRemarkPlugin) // custom remark plugin
.use(vfmHtml)
.use(myRehypePlugin) // custom rehype plugin
.processSync('# Hello');
}
// editPlugins — modify the built-in plugin list
const processor = VFM({
editPlugins: (plugins) => ({
...plugins,
mdastPlugins: plugins.mdastPlugins.filter(
([plugin]) => plugin !== myUnwantedPlugin,
),
}),
});
```
### Response
- **processor** (object) - A unified `Processor` instance.
```
--------------------------------
### HTML Code Block
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
Represents an HTML code block, often used for displaying code examples or structure.
```html
functionmain(){}
```
--------------------------------
### Initialize Unified Processor with VFM
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Create a VFM processor instance with the `partial: true` option for advanced usage.
```javascript
import { VFM } from '@vivliostyle/vfm';
const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();
```
--------------------------------
### Use VFM with Vivliostyle CLI
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Integrate VFM with the Vivliostyle CLI for building HTML books from Markdown, including custom stylesheets.
```bash
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
```
--------------------------------
### Graduate to Release
Source: https://github.com/vivliostyle/vfm/blob/main/CONTRIBUTING.md
Finalize the release by running the npm release script or using release-it without pre-release flags.
```bash
npm run release
```
```bash
release-it
```
--------------------------------
### `stringify` Option: `style`
Source: https://context7.com/vivliostyle/vfm/llms.txt
Sets one or more `` elements in the document ``. Accepts a single string or an array of strings.
```APIDOC
## `stringify` Option: `style`
Sets one or more `` elements in the document ``. Accepts a single string or an array of strings.
### Parameters
#### Request Body (stringify options)
- **style** (string | string[]) - Required - A single URL or an array of URLs for the stylesheets.
### Request Example
```js
import { stringify } from '@vivliostyle/vfm';
// Single stylesheet
stringify('# Hello', { style: 'https://example.com/book.css' });
// will contain:
// Multiple stylesheets
stringify('# Hello', {
style: [
'https://example.com/book.css',
'https://example.com/extra.css',
],
});
// will contain both elements in order
```
```
--------------------------------
### Create a Reusable VFM Processor
Source: https://context7.com/vivliostyle/vfm/llms.txt
Instantiate a reusable `unified` Processor with the VFM pipeline using the `VFM` factory. This is useful for multiple conversions, AST inspection, or integrating custom plugins.
```javascript
import { VFM } from '@vivliostyle/vfm';
import unified from 'unified';
import vfmParse from '@vivliostyle/vfm/lib/revive-parse';
import vfmHtml from '@vivliostyle/vfm/lib/revive-rehype';
// Simple reusable processor
const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();
// Output:
Hello
// Custom unified pipeline — splice in your own remark/rehype plugins
function customPipeline() {
unified()
.use(vfmParse)
.use(myRemarkPlugin) // custom remark plugin
.use(vfmHtml)
.use(myRehypePlugin) // custom rehype plugin
.processSync('# Hello');
}
// editPlugins — modify the built-in plugin list before execution
import { VFM } from '@vivliostyle/vfm';
const processor = VFM({
editPlugins: (plugins) => ({
...plugins,
// Remove or reorder mdastPlugins / hastPlugins as needed
mdastPlugins: plugins.mdastPlugins.filter(
([plugin]) => plugin !== myUnwantedPlugin,
),
}),
});
```
--------------------------------
### Bump Pre-release Version
Source: https://github.com/vivliostyle/vfm/blob/main/CONTRIBUTING.md
Increment the pre-release version using npm scripts or release-it with the 'next' npm tag.
```bash
npm run release:pre
```
```bash
release-it --preRelease --npm.tag=next
```
--------------------------------
### `readMetadata(md, customKeys?)`
Source: https://context7.com/vivliostyle/vfm/llms.txt
Parses the YAML frontmatter of a Markdown string and returns a typed `Metadata` object. Unknown keys are converted to `` entries, while keys listed in `customKeys` are stored as-is under `metadata.custom`.
```APIDOC
## `readMetadata(md, customKeys?)`
Parses the YAML frontmatter of a Markdown string and returns a typed `Metadata` object without performing a full HTML conversion. Unknown keys are converted to `` entries; keys listed in `customKeys` are stored as-is under `metadata.custom`.
### Parameters
#### Path Parameters
- **md** (string) - Required - The Markdown string to parse.
- **customKeys** (string[]) - Optional - An array of keys to preserve as-is in the `custom` property of the metadata object.
### Request Example
```js
import { readMetadata } from '@vivliostyle/vfm';
const md = `---\nkey1: value1\nkey2: value2\n---\n# Content\n`;
const metadata = readMetadata(md, ['key1']);
console.log(metadata);
// { key1: 'value1', custom: { key2: 'value2' } }
```
### Response
#### Success Response (Metadata Object)
- **metadata** (object) - An object containing the parsed metadata.
- **custom** (object) - Contains keys specified in `customKeys`.
- Other keys are parsed as metadata properties or converted to `` tags.
### Response Example
```json
{
"id": "my-page",
"lang": "en",
"dir": "ltr",
"class": "my-class",
"title": "Title",
"vfm": {
"math": false,
"theme": "sample.css",
"partial": false,
"hardLineBreaks": true
}
}
```
```
--------------------------------
### Basic Code Block
Source: https://github.com/vivliostyle/vfm/blob/main/docs/vfm.md
Demonstrates a basic fenced code block in VFM. VFM uses Prism for syntax highlighting.
```markdown
```javascript
function main() {}
```
```
--------------------------------
### Unified plugin integration
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Demonstrates how to integrate VFM as a Unified plugin within a processing pipeline. This allows for custom remark and rehype plugins to be used alongside VFM's parsing and transformation capabilities.
```APIDOC
## Unified plugin integration
### Description
Integrate VFM as a Unified plugin. This allows for the use of custom remark and rehype plugins in conjunction with VFM's parsing and transformation capabilities.
### Method
`unified().use(plugin).processSync(markdown)`
### Parameters
#### Plugins
- **vfm**: `@vivliostyle/vfm/lib/revive-parse` - VFM parser plugin.
- **html**: `@vivliostyle/vfm/lib/revive-rehype` - VFM rehype plugin.
- **customRemarkPlugin**: User-defined remark plugin.
- **customRehypePlugin**: User-defined rehype plugin.
### Request Example
```js
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');
}
```
```
--------------------------------
### Unified processor
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Shows how to create and use a Unified processor with VFM for advanced Markdown processing. This allows for custom remark and rehype plugins to be integrated into the processing pipeline.
```APIDOC
## Unified processor
### Description
Use the VFM Unified processor for advanced Markdown parsing and transformation. This enables the integration of custom remark and rehype plugins.
### Method
`VFM({ partial: boolean })`
### Parameters
#### Options
- **partial** (boolean) - Optional - If `true`, enables partial processing.
### Request Example
```js
import { VFM } from '@vivliostyle/vfm';
const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();
```
```
--------------------------------
### VFM Math Equations Syntax
Source: https://context7.com/vivliostyle/vfm/llms.txt
Illustrates VFM's syntax for inline math ($...$) and display math ($$...$$). MathJax is automatically included when math syntax is detected.
```markdown
Inline: $E = mc^2$
Display:
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
Multi-line inline: $x = y
1 + 1 = 2$
```
```html
```
--------------------------------
### VFM Options: `style`
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
The `style` option allows you to specify CSS stylesheets to be linked in the generated HTML. It can accept a single URL or an array of URLs.
```APIDOC
## `style` Option
### Description
Specifies CSS stylesheet(s) to be included in the HTML output.
### Usage
- **Single Style:** `stringify(markdown, { style: 'https://example.com/style.css' })`
- **Multiple Styles:** `stringify(markdown, { style: ['https://example.com/style1.css', 'https://example.com/style2.css'] })`
### Example Output (Single Style)
```html
```
```
--------------------------------
### User-Specified Metadata for Stringify
Source: https://github.com/vivliostyle/vfm/blob/main/README.md
Provide user-specified metadata directly to the `stringify` function. This takes precedence over Frontmatter metadata.
```javascript
stringify(
'# Title',
{},
{ title: 'My Page', body: [{ name: 'id', value: 'page' }] },
);
```
--------------------------------
### Add Stylesheets with stringify 'style' option
Source: https://context7.com/vivliostyle/vfm/llms.txt
The `style` option in `stringify` allows you to add `` elements to the document head. It accepts a single URL or an array of URLs.
```javascript
import { stringify } from '@vivliostyle/vfm';
// Single stylesheet
stringify('# Hello', { style: 'https://example.com/book.css' });
// will contain:
//
```
```javascript
// Multiple stylesheets
stringify('# Hello', {
style: [
'https://example.com/book.css',
'https://example.com/extra.css',
],
});
// will contain both elements in order
```
--------------------------------
### `stringify` Option: `replace` (Hooks)
Source: https://context7.com/vivliostyle/vfm/llms.txt
Provides a post-parse text-replacement pipeline. Each rule has a `test` regex and a `match` function receiving the regex match array and a [hastscript](https://github.com/syntax-tree/hastscript) `h` builder. Used to implement custom inline syntax such as speech balloons, icons, or custom markup.
```APIDOC
## `stringify` Option: `replace` (Hooks)
Provides a post-parse text-replacement pipeline. Each rule has a `test` regex and a `match` function receiving the regex match array and a [hastscript](https://github.com/syntax-tree/hastscript) `h` builder. Used to implement custom inline syntax such as speech balloons, icons, or custom markup.
### Parameters
#### Request Body (stringify options)
- **replace** (Array