Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vivliostyle/vfm
⬇️ Open and extendable Markdown syntax and toolchain.
https://github.com/vivliostyle/vfm
markdown vfm vivliostyle
Last synced: 17 days ago
JSON representation
⬇️ Open and extendable Markdown syntax and toolchain.
- Host: GitHub
- URL: https://github.com/vivliostyle/vfm
- Owner: vivliostyle
- License: other
- Created: 2020-01-14T03:44:23.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-03-12T09:35:01.000Z (9 months ago)
- Last Synced: 2024-11-17T23:51:32.515Z (25 days ago)
- Topics: markdown, vfm, vivliostyle
- Language: TypeScript
- Homepage: https://vivliostyle.github.io/vfm/#/vfm
- Size: 1.6 MB
- Stars: 72
- Watchers: 16
- Forks: 12
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-vivliostyle - @vivliostyle/vfm - Vivliostyle Flavored Markdown (VFM) is a Markdown syntax optimized for book authoring. (Official)
- awesome-vivliostyle - @vivliostyle/vfm - Vivliostyle Flavored Markdown (VFM) is a Markdown syntax optimized for book authoring. (Official)
README
[](https://github.com/vivliostyle/vfm/actions?query=CI)
[][npm-url]
[][npm-url]
[npm-url]: https://npmjs.org/package/@vivliostyle/vfm
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](#install)
- [Use](#use)
- [Usage with `vivliostyle` command](#usage-with-vivliostyle-command)
- [API](#api)
- [Options](#options)
- [`style` (default: `undefined`)](#style-default-undefined)
- [`partial` (default: `false`)](#partial-default-false)
- [`title` (default: `undefined`)](#title-default-undefined)
- [`language` (default: `undefined`)](#language-default-undefined)
- [`hardLineBreaks` (default: `false`)](#hardlinebreaks-default-false)
- [`disableFormatHtml` (default: `false`)](#disableformathtml-default-false)
- [`math` (default: `true`)](#math-default-true)
- [Advanced usage](#advanced-usage)
- [Unified processor](#unified-processor)
- [Unified plugin](#unified-plugin)
- [readMetadata](#readmetadata)
- [User-specified metadata](#user-specified-metadata)
- [Spec](#spec)
- [Principles](#principles)
- [Links](#links)
- [Contribution](#contribution)
- [Maintainers](#maintainers)
## Install
```bash
npm install -g @vivliostyle/vfm
```
## Use
```bash
vfm --help
vfm README.md
echo "# Hello" | vfm
```
### Usage with `vivliostyle` command
```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
```
## API
```bash
npm install --save @vivliostyle/vfm
# or
yarn add @vivliostyle/vfm
```
```js
import { stringify } from '@vivliostyle/vfm';
console.log(
stringify(`
# はじめに
{Vivliostyle|ビブリオスタイル}の世界へようこそ。
`),
);
```
This snippet will generates:
```html
はじめに
はじめに
Vivliostyleビブリオスタイルの世界へようこそ。
```
### Options
#### `style` (default: `undefined`)
Set the specified value as the `href` attribute of ``.
```js
stringify('# Hello', { style: 'https://example.com/book.css' });
```
will generates:
```html
Hello
```
`style` can be an array of styles.
```js
stringify('# Hello', {
style: ['https://example.com/book.css', 'https://example.com/extra.css'],
});
```
will generates:
```html
Hello
```
#### `partial` (default: `false`)
If `true` is specified, only the HTML defined in `` is output.
```js
stringify('# Hello', { partial: true });
```
will generates:
```html
Hello
```
#### `title` (default: `undefined`)
Set the specified value as the text of ``.
```js
stringify('# Hello', { title: 'Hello' });
```
will generates:
```html
Hello
Hello
```
#### `language` (default: `undefined`)
Set the specified value as the `lang` attribute of ``.
```js
stringify('# Hello', { language: 'ja' });
```
will generates:
```html
Hello
```
#### `hardLineBreaks` (default: `false`)
Converts line breaks to `
`.
```js
stringify(
`
new
line
`,
{ hardLineBreaks: true },
);
```
will generates:
```html
new
line
```
#### `disableFormatHtml` (default: `false`)
Disable automatic HTML format. Explicitly specify true if want unformatted HTML during development or debug.
```js
stringify(
`text`,
{ disableFormatHtml: true },
);
```
will generates:
```html
text
```
#### `math` (default: `true`)
Handles math syntax. The default value is `true`, which is valid.
```js
stringify(
`$x = y$`
);
```
will generates:
```html
\(x = y\)
```
To explicitly disable it, specify `false` for this option or `math: false` for Markdown's Frontmatter.
```js
stringify(
`$x = y$`,
{ math: false }
);
```
will generates:
```html
$x = y$
```
### Advanced usage
#### Unified processor
```js
import { VFM } from '@vivliostyle/vfm';
const processor = VFM({ partial: true });
const html = processor.processSync('# Hello').toString();
```
#### Unified plugin
```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');
}
```
#### 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`: `String` Markdown text.
- `customKeys`: `String[]` A collection of key names to be ignored by meta processing.
- returns:
- `metadata`: `Metadata` Metadata.
```js
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](https://vivliostyle.github.io/vfm/#/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`.
```js
import { readMetadata } from '@vivliostyle/vfm'
const md = `---
title: 'Title'
tags: ['foo', 'bar']
---
`;
const metadata = readMetadata(md, ['tags']);
console.log(metadata);
```
Results:
```js
{
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`
```js
stringify(
'# Title',
{},
{ title: 'My Page', body: [{ name: 'id', value: 'page' }] },
);
```
HTML:
```html
My Page
Title
```
## Spec
[Current Status](https://github.com/vivliostyle/vfm/projects/1)
### Principles
1. **Open**: steadily improving through open discussion and feedback from the vast community.
1. **Consistent**: Provides reference implementation for parsing and converting VFM to HTML, allowing other non Vivliostyle projects to use this syntax for their purposes.
### Links
- [Vivliostyle Flavored Markdown](https://vivliostyle.github.io/vfm/#/vfm)
- [Theme Design Guidelines](https://github.com/vivliostyle/themes/tree/master/DESIGN.md)
## Contribution
We want you to:
- Join [Discussion](https://github.com/vivliostyle/vfm/issues) to improve spec
- Implement [alpha-stage specs](https://github.com/vivliostyle/vfm/issues?q=is%3Aissue+is%3Aopen+label%3Astage%3Aalpha) and send a PR
- Test [beta-stage features](https://github.com/vivliostyle/vfm/issues?q=is%3Aissue+is%3Aopen+label%3Astage%3Abeta) and report a bug
[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/0)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/1)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/2)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/3)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/4)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/5)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/6)[](https://sourcerer.io/fame/uetchy/vivliostyle/vfm/links/7)
### Maintainers
- [Akabeko](https://github.com/akabekobeko)
- [Yasuaki Uechi](https://github.com/uetchy)