Transmark 3000
Transclusive markdown.
Basics
Transmark
allows to transclude
sections of markdown.
Given the following two markdown files:
File 1:
# Hello Universe
## Hello World
--- meta
uuid: 123
---
Some common content.
## Hello Space
File 2:
# Hello there
@[snippet](123)
Using transmark we can create the following document from it.
File 3:
# Hello there
Some common content.
Table of contents
Installation
npm install --save transmark
Usage
import fs from 'fs';
import {parse, transform, toHtml} from 'transmark';
// Read the markdown file.
const text = fs.readFileSync('./file.md').toString();
// Parse the raw markdown into a markdown token zipper and an object
// containing all meta data.
const [markdown, metaData] = parse(text);
// Transform the markdown token zipper into it's final representation. This
// step does all the transclusion.
const transformed = transform(metaData, markdown);
// Render the markdown token zipper to HTML.
const html = toHtml(transformed);
API
Parsing
parse
Parse a markdown string.
Parameters
-
src
string A string in markdown format. -
customHandlers
[Object](default {}) Provide custom handler functions for meta block fields. -
meta
[Object](default {}) Attach this as meta data to the zipper.
Returns [Zipper, Object] Returns a tuple containing the token stream and a meta data object.
extend
Extend the markdown-it parser with custom plugins. Any valid markdowm-it
plugin is allowed. This function returns nil
;
Parameters
-
plugin
Object The markdown-it plugin.
Validating
validator
Apply a list of validation functions to a value.
Parameters
Returns (Valid | Invalid)
check
Create a valid check function.
Parameters
Returns Function
Transforming
transform
Transform the markdown to the final form.
Parameters
-
metaData
Object The transmark state received from parse. -
customTransformers
Object Extend the transmark transformation. -
source
Zipper A transmark zipper to transform.
Returns Zipper
Rendering
toHtml
Render a markdown token zipper to HTML.
Parameters
-
tokens
Zipper The markdown token zipper.
Returns string The rendered HTML.
Markdown
meta
Parse the contents of a meta block using YAML.
Parameters
-
tokens
Zipper The markdown tokens zipper.
Returns Object The meta data object.
forwardByHeader
Forward one header.
Parameters
-
tokens
Zipper The markdonw tokens zipper.
Returns Zipper The zipper with the cursors moved after the header.
forwardToNextSection
Move the markdown token stream one section.
Parameters
-
tokens
Zipper The markdown tokens zipper.
Returns Zipper The zipper with the cursor moved by one section.
sliceSection
Slice the section of a markdown zipper.
Parameters
-
tokens
Zipper The zipper to slice.
Returns Zipper The section that got sliced.
sliceHeading
Slice the heading of a section.
Parameters
-
tokens
Zipper The zipper to slice.
Returns Zipper The heading that got sliced.
subSections
Split the markdown zipper into it's subsections.
Parameters
-
tokens
Zipper The zipper to split up.
Returns Array<Zipper> The sub sections of the markdown zipper.
balanceSection
Balance the section levels towards a new root level.
Parameters
-
rootLevel
string The section heading tag to use as the root level. -
tokens
Zipper The markdown token zipper.
Returns Zipper The markdown token zipper with the section heading levels rebalanced.
insertSection
Insert a markdown token zipper after the current element of another zipper.
Parameters
-
section
Zipper The zipper to insert. -
tokens
Zipper The target zipper.
Returns Zipper A new zipper with section
inserted.
replaceToken
Replace the current token with another zipper.
Parameters
-
section
Zipper The section that replaces. -
tokens
Zipper The zipper to replace the current token.
sectionTitle
Get the current section title.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns string The title.
metaSection
Parse the next meta block.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Object A key-value meta object.
currentHeading
Get the current heading level.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns string The current heading tag.
cutHeading
Cut out a heading block.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Zipper A new version of tokens
with the heading removed.
cutMeta
Cut out a meta block.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Zipper A new version of tokens
with the meta block removed.
cutHeader
Cut out a header.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Zipper A new version of tokens
with the heading and the meta
block removed.
cutMarker
Cut out a meta marker.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Zipper A new version of tokens
with the meta marker removed.
cutSectionContents
Cut the contents of a section, but keep the header.
Parameters
-
tokens
Zipper A markdown token zipper.
Returns Zipper A new version of tokens
with the contents of the section
removed.
Markdown-it Plugins
markdownMetaMarker
Create a new marker plugin for markdown-it.
Parameters
-
name
string The name of this marker.
Returns Object
markdownMetaBlock
Extend markdown-it to parse meta blocks.
Parameters
-
md
Object The markdown-it parser object. -
options
[Object](default {}) configuration options for this plugin.
markdownSnippetMarker
A snippet meta marker.
markdownReferenceMarker
A reference marker