https://github.com/flaviotordini/markdown-it-yaml
Insert YAML documents inside Markdown and have them render to HTML using Mustache templates
https://github.com/flaviotordini/markdown-it-yaml
markdown markdown-it markdown-it-plugin mustache yaml
Last synced: 23 days ago
JSON representation
Insert YAML documents inside Markdown and have them render to HTML using Mustache templates
- Host: GitHub
- URL: https://github.com/flaviotordini/markdown-it-yaml
- Owner: flaviotordini
- License: mit
- Created: 2022-07-30T13:20:07.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-09-06T12:32:05.000Z (over 3 years ago)
- Last Synced: 2025-01-22T12:31:04.346Z (over 1 year ago)
- Topics: markdown, markdown-it, markdown-it-plugin, mustache, yaml
- Language: JavaScript
- Homepage:
- Size: 20.5 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# markdown-it-yaml
Insert YAML documents inside Markdown and have them render to HTML using Mustache templates.
This is useful when you need structured data in your Markdown documents. You get a very easy syntax to write the data (YAML) and total control on HTML output. Objects can be anything: images, galleries, polls, family trees, whatever.
## Example
Example input:
# Title
Some content.
```yaml
type: image
src: cat.jpg
alt: A cat
caption: The cat is on the table
credit: Flavio
```
More Markdown content.
Since `type` is `image`, a mustache template named `image.html` must be created in your template directory.
The template directory defaults to the current working directory. You should set it in the options.
A Mustache template would look like:
```handlebars
{{#caption}}{{caption}}{{/caption}}
{{#credit}}
{{credit}}{{/credit}}
```
Output:
```html
Title
Some content.
The cat is on the table
Flavio
More Markdown content.
```
## Syntax
I chose the standard code block marker ```yaml as the default marker in order to get nice editing and preview for authors and not introduce a new Markdown syntax. It can be changed in the options.
By appending some other word after ```yaml you can disable this plugin for a specific YAML code block:
```yaml norender
this: won't get mustached
```
## API
### Object List
An array of the parsed YAML blocks can be accessed at `env.objects` after the Markdown document has been processed. This can be useful to generate table of contents, statistics, export data, etc. See the Usage example below.
### Object callback
Specify a `onObject` callback in the options to be notified of each parsed YAML document. You can then modify it as you need. See the Usage example below.
## Install
Coming soon
```bash
$ npm install markdown-it-yaml
```
## Usage
Minimal usage:
```js
const md = require('markdown-it')();
md.use(require('markdown-it-yaml'), { templateDir: 'myDir' }
const html = md.render(markdown, {});
```
Complete usage:
```js
const md = require('markdown-it')();
md.use(require('markdown-it-yaml'), {
// optional, these are the defaults
templateDir: '.',
markerStart: '```yaml',
markerEnd: '```',
typeKey: 'type',
templateExtension: '.html',
autoNumbering: false,
numberKey: 'number',
render: (template, obj) => {
return myFavoriteTemplateEngine(template, obj);
},
onObject: (obj) => {
// do whatever you want with the data
},
debug: false
});
const markdown = 'Load your Markdown from somewhere...';
const env = {
someExtraTemplateData: 'foo'
};
const html = md.render(markdown, env);
// Access the parsed YAML objects
for (const obj of env.objects) {
console.log(obj);
}
```
## Support
I'll approve pull requests that are easy to understand. Feel free to open and I'll give my feedback.
If you need extra features, I'm available for hire.
## License
MIT © [Flavio Tordini](https://flavio.tordini.org/)