Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/t-ski/markdocs

Simple Markdown to HTML translator supporting custom elements.
https://github.com/t-ski/markdocs

markdown transpiler

Last synced: about 10 hours ago
JSON representation

Simple Markdown to HTML translator supporting custom elements.

Host: GitHub
URL: https://github.com/t-ski/markdocs
Owner: t-ski
Created: 2022-07-02T00:32:39.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2024-07-17T18:15:25.000Z (4 months ago)
Last Synced: 2024-07-17T22:25:50.850Z (4 months ago)
Topics: markdown, transpiler
Language: JavaScript
Homepage:
Size: 73.2 KB
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

        # markdocs

Simple and fast Markdown to HTML translator supporting custom elements.

## Installation

``` bash

npm i t-ski/markdocs

```

``` js

const markdocs = require("markdocs");

```

## Translation

### From string

``` js

const result = markdocs.translateStr(`

    # Title

    This is a **paragraph**.

`);

```

↳

``` html

Title



    This is a paragraph.



```

### From file

``` js

const result = markdocs.translateFile("./docs/INTRO.md");

```

#### Overloads

• Invoke callback on translation result:

``` js

const result = markdocs.translateFile("./docs/INTRO.md", result => {

    console.log(`Length of HTML representation: ${result.length}`);

});

```

• Write translation result to file at given path:

``` js

const result = markdocs.translateFile("./docs/INTRO.md", "./web/introduction.html");

```

## Block Elements

Each line in Markdown code represents a block element (a paragraph if not specific). A block element is indicated with a line prefix followed by a space character. The succeeding character sequence is considered its content.

### Declaration syntax

```

new markdocs.BlockElement(tokenName, tagNameOrWrapper, prefix, groupTagName, options)

```

| Parameter | Type | Purpose |

| --------- | ---- | ------- |

| `tokenName` | **String** | *Token name for internal organization* |

| `tagNameOrWrapper` | **String, Function** | *Tag name (automatic) or function for (custom) wrapping* |

| `prefix` | **String, RegExp** | *Prefix to associate with the element (RegExp escaped if given a string)* |

| `groupTagName` | **String** | *Element compound group name to inject surrounding tag upon translation* |

| `options` | **Object** | *Options object* |

### Options

| Property | Type | Purpose |

| -------- | ---- | ------- |

| `type` | **BlockElement.Type** | *Block element type* |

| `inlineStyles` | **Boolean** | *Whether to parse inline elements and apply related styles to the element content* |

### Block element types

| Name | Description |

| ---- | ----------- |

| `FENCED` | *A block is opened until the next occurrence of the prefix (acting as a suffix). The lines in between are representing the respective block content.* |

| `STANDALONE` | *A block does only consist of the prefix and does not allow for content. A standlone block is rendered as an empty tag.* |

### Custom wrapper

A custom wrapper function is getting passed either a content string or – iff associated with a fenced element – a content string array with the indicating line content (index 0), the spanned body contents (index 1, concatenated lines) and the closing line content (index 2). The returned value is used as the wrapped substitute for the raw parsing in the translation.

### Example

``` js

new markdocs.BlockElement("Custom Block Element", "q", "|", "div");

```

``` js

new markdocs.BlockElement("Custom Fenced Block Element", code => {

    return `
\n${code}\n`;

}, "|", null, {

    inlineStyles: false,

    type: markdocs.BlockElement.Type.FENCED

});

```

## Inline Elements

Inline elements represent a certain (recurring) pattern occurrence in block contents. They are used for applying generic styles.

### Declaration syntax

```

new markdocs.InlineElement(tokenName, tagNameOrWrapper, pattern, options)

```

| Parameter | Type | Purpose |

| --------- | ---- | ------- |

| `tokenName` | **String** | *Token name for internal organization* |

| `tagNameOrWrapper` | **String, Function** | *Tag name (automatic) or function for (custom) wrapping* |

| `pattern` | **RegExp** | *Occurrence pattern* |

| `options` | **Object** | *Options object* |

### Options

| Property | Type | Purpose |

| -------- | ---- | ------- |

| `priority` | **Number** | *Numeric (increasing) value to manipulate the parsing order (useful for ambiguous contexts)* |

### Example

``` js

new markdocs.InlineElement("Custom Inline Element", "span" , "::");

```

  

---

## Default Elements (supported MD)

### Block elements

- [x] Headings {1, ... , 6}

```

# Heading {#optional-id}

```

- [x] Blockquote  

```

> Blockquote...

```

- [x] Ordered List  

```

1. List item

2. List item

```

- [x] Unordered List  

```

- List item

- List item

```

- [x] Horizontal Rule  

```

---

```

- [x] Table  

```

| Table head 1    | Table head 2    |

| --------------- | --------------: |

| Table entry 1.1 | Table entry 2.1 |

| Table entry 1.2 | Table entry 2.2 |

```

- [x] Fenced Code  


``` js

alert("Hello world!");

```



### Inline elements

- [x] Link  

```

[Click here](./link.html)

```

- [x] Image  

```

![Logo](./img/logo.svg)

```

- [x] Bold  

```

**Bold text**

```

- [x] Italic  

```

*Italic text*

```

- [x] Strikethrough  

```

~Strikethrough text~

```

- [x] Highlight  

```

==Highlighted text==

```

- [x] Subscript  

```

A~sub~

```

- [x] Superscript  

```

B^sup^

```

- [x] Inline code  


`INLINE CODE`



## 

_{© Thassilo Martin Schiepanski}