MarkdownUtils

11 Apr

Library "MarkdownUtils"
This library shows all of CommonMark's formatting elements that are currently (2024-03-30)
available in Pine Script® and gives some hints on how to use them.

The documentation will be in the tooltip of each of the following functions. It is also
logged into Pine Logs by default if it is called. We can disable the logging by setting `pLog = false`.

mediumMathematicalSpace()
  Medium mathematical space that can be used in e.g. the library names like `Markdown Utils`.
  Returns: The medium mathematical space character U+205F between those double quotes " ".

zeroWidthSpace()
  Zero-width space.
  Returns: The zero-width character ​U+200B between those double quotes "​".

stableSpace(pCount)
  Consecutive space characters in Pine Script® are replaced by a single space character on output.
Therefore we require a "stable" space to properly indent text e.g. in Pine Logs. To use it in code blocks
of a description like this one, we have to copy the 2(!) characters between the following reverse brackets instead:

# >​ <

Those are the zero-width character ​U+200B and a space.

Of course, this can also be used within a text to add some extra spaces.
  Parameters:
    pCount (simple int)
  Returns: A zero-width space combined with a space character.

headers(pLog)
  Headers

```

# H1

## H2

### H3

#### H4

##### H5

###### H6

```
​

*results in*

​

# H1

## H2

### H3

#### H4

##### H5

###### H6

​

*Best practices*: Add blank line before and after each header.
  Parameters:
    pLog (bool)

paragrahps(pLog)
  Paragraphs

```
First paragraph

Second paragraph
```
​

*results in*

​

First paragraph

Second paragraph

​
  Parameters:
    pLog (bool)

lineBreaks(pLog)
  Line breaks

```
First row
Second row
```
​

*results in*

​

First row\
Second row
  Parameters:
    pLog (bool)

emphasis(pLog)
  Emphasis

With surrounding `*` and `~` we can emphasize text as follows. All emphasis can be arbitrarily combined.


```
*Italics*, **Bold**, ***Bold italics***, ~~Scratch~~
```
​

*results in*

​

*Italics*, **Bold**, ***Bold italics***, ~~Scratch~~

​
  Parameters:
    pLog (bool)

blockquotes(pLog)
  Blockquotes

Lines starting with at least one `>` followed by a space and text build block quotes.

```
Text before blockquotes.

> 1st main blockquote
>
> 1st main blockquote
>
>> 1st 1-nested blockquote
>
>>> 1st 2-nested blockquote
>
>>>> 1st 3-nested blockquote
>
>>>>> 1st 4-nested blockquote
>
>>>>>> 1st 5-nested blockquote
>
>>>>>>> 1st 6-nested blockquote
>
>>>>>>>> 1st 7-nested blockquote
>
> 2nd main blockquote, 1st paragraph, 1st row\
> 2nd main blockquote, 1st paragraph, 2nd row
>
> 2nd main blockquote, 2nd paragraph, 1st row\
> 2nd main blockquote, 2nd paragraph, 2nd row
>
>> 2nd nested blockquote, 1st paragraph, 1st row\
>> 2nd nested blockquote, 1st paragraph, 2nd row
>
>> 2nd nested blockquote, 2nd paragraph, 1st row\
>> 2nd nested blockquote, 2nd paragraph, 2nd row

Text after blockquotes.
```
​

*results in*

​

Text before blockquotes.

> 1st main blockquote
>
>> 1st 1-nested blockquote
>
>>> 1st 2-nested blockquote
>
>>>> 1st 3-nested blockquote
>
>>>>> 1st 4-nested blockquote
>
>>>>>> 1st 5-nested blockquote
>
>>>>>>> 1st 6-nested blockquote
>
>>>>>>>> 1st 7-nested blockquote
>
> 2nd main blockquote, 1st paragraph, 1st row\
> 2nd main blockquote, 1st paragraph, 2nd row
>
> 2nd main blockquote, 2nd paragraph, 1st row\
> 2nd main blockquote, 2nd paragraph, 2nd row
>
>> 2nd nested blockquote, 1st paragraph, 1st row\
>> 2nd nested blockquote, 1st paragraph, 2nd row
>
>> 2nd nested blockquote, 2nd paragraph, 1st row\
>> 2nd nested blockquote, 2nd paragraph, 2nd row

Text after blockquotes.

​

*Best practices*: Add blank line before and after each (nested) blockquote.
  Parameters:
    pLog (bool)

lists(pLog)
  Paragraphs

#### Ordered lists

The first line starting with a number combined with a delimiter `.` or `)` starts an ordered
list. The list's numbering starts with the given number. All following lines that also start
with whatever number and the same delimiter add items to the list.

#### Unordered lists

A line starting with a `-`, `*` or `+` becomes an unordered list item. All consecutive items with
the same start symbol build a separate list. Therefore every list can only have a single symbol.

#### General information

To start a new list either use the other delimiter or add some non-list text between.

List items in Pine Script® allow line breaks but cannot have paragraphs or blockquotes.

Lists Pine Script® cannot be nested.


```
1) 1st list, 1st item, 1st row\
​ 1st list, 1st item, 2nd row
1) 1st list, 2nd item, 1st row\
​ 1st list, 2nd item, 2nd row

1) 1st list, 2nd item, 1st row\
​ 1st list, 2nd item, 2nd row
1. 2nd list, 1st item, 1st row\
​ 2nd list, 1st item, 2nd row

Intermediary text.

1. 3rd list

Intermediary text (sorry, unfortunately without proper spacing).

8. 4th list, 8th item
8. 4th list, 9th item

Intermediary text.

- 1st list, 1st item
- 1st list, 2nd item

* 2nd list, 1st item
* 2nd list, 2nd item

Intermediary text.

+ 3rd list, 1st item
+ 3rd list, 2nd item
```
​

*results in*

​

1) 1st list, 1st item, 1st row\
1st list, 1st item, 2nd row
1) 1st list, 2nd item, 1st row\
1st list, 2nd item, 2nd row

1) 1st list, 2nd item, 1st row\
1st list, 2nd item, 2nd row
1. 2nd list, 1st item, 1st row\
2nd list, 1st item, 2nd row

Intermediary text.

1. 3rd list

Intermediary text (sorry, unfortunately without proper spacing).

8. 4th list, 8th item
8. 4th list, 9th item

Intermediary text.

- 1st list, 1st item
- 1st list, 2nd item

* 2nd list, 1st item
* 2nd list, 2nd item

Intermediary text.

+ 3rd list, 1st item
+ 3rd list, 2nd item

​
  Parameters:
    pLog (bool)

code(pLog)
  ### Code

`` `Inline code` `` is formatted like this.

To write above line we wrote `` `​` `Inline code` `​` ``.

And to write that line we added another pair of `` `​` `` around that code and
a zero-width space of function [zeroWidthSpace()] between the inner `` `​` ``.

### Code blocks

can be formatted like that:

~~~
```
export method codeBlock() =>
​ ​ ​ ​ "code block"
```
~~~

Or like that:

```
~~~
export method codeBlock() =>
​ ​ ​ ​ "code block"
~~~
```

To write `​```​` within a code block we can either surround it with `~~~`.
Or we "escape" those ​​`​```​` by only the zero-width space of function [stableSpace](stableSpace) in between.

To escape \` within a text we use `` \` ``.
​
  Parameters:
    pLog (bool)

horizontalRules(pLog)
  Horizontal rules

At least three connected `*`, `-` or `_` in a separate line build a horizontal rule.

```
Intermediary text.

---

Intermediary text.

***

Intermediary text.

___

Intermediary text.
```
​

*results in*

​

Intermediary text.

---

Intermediary text.

***

Intermediary text.

___

Intermediary text.

​

*Best practices*: Add blank line before and after each horizontal rule.
  Parameters:
    pLog (bool)

tables(pLog)
  Tables

A table consists of a single header line with columns separated by `|`
and followed by a row of alignment indicators for either left (`---`, `:---`), centered (`:---:`) and right (`---:`)
A table can contain several rows of data.

The table can be written as follows but hasn't to be formatte like that. By adding [stableSpace](stableSpace)
on the correct side of the header we could even adjust the spacing if we don't like it as it is. Only around
the column separator we should only use a usual space on each side.

```
Header 1​ ​ ​ ​ ​ ​ ​ ​​ | Header 1​ ​​ |​ ​ Header 2​​​ ​ |​ ​ Header 3
--- | :--- | :----: | ---:
Left (Default) | Left | Centered | Right
Left (Default) | Left | Centered | Right
```


*results in*

​

Header 1​ ​ ​ ​ ​ ​ ​ ​​ | Header 1​ ​​ |​ ​ Header 2​​​ ​ |​ ​ Header 3
--- | :--- | :----: | ---:
Left (Default) | Left | Centered | Right
Left (Default) | Left | Centered | Right

​
  Parameters:
    pLog (bool)

links(pLog)
  ## Links.

### Inline-style

`[Trading View, inline-style link with default tooltip](Here should be the link to the TradingView homepage)`\
results in [Trading View, inline-style link with default tooltip](Here should be the link to the TradingView homepage)

`[Trading View, inline-style link with "Trading View tooltip"](Here should be the link to the TradingView homepage "Trading View tooltip")`\
results in [Trading View, inline-style link with "Trading View tooltip"](Here should be the link to the TradingView homepage "Trading View tooltip")

### Reference-style

One can also collect all links e.g. at the end of a description and use a reference to that as follows.

`[Trading View, reference-style link with case-insensitive reference text][Separate Trading View reference]`\
results in [Trading View, reference-style link with case-insensitive reference text][Separate Trading View reference].

`[Trading View, reference-style link with reference number][1]`\
results in [Trading View, reference-style link with reference number][1].

`[Trading View, reference-style where the link text is the reference]`\
results in [Trading View, reference-style where the link text is the reference].

`[I'm a relative reference to a repository file](../tradingview/scripts/readme)`\
results in [I'm a relative reference to a repository file](../tradingview/scripts/readme).

### URLs and email

URLs are also identified by the protocol identifier, email addresses by `@`. They can also be surrounded by `<` and `>`.

Input | Result
--- | ---
`Here should be the link to the TradingView homepage` | Here should be the link to the TradingView homepage
`<Here should be the link to the TradingView homepage>` | <Here should be the link to the TradingView homepage>
`supporttradingview.com` | supporttradingview.com
`<supporttradingview.com>` | <supporttradingview.com>

## Images

We can display gif, jp(e)g and png files in our documentation, if we add `!` before a link.

### Inline-style:

``

results in

\

### Reference-style:

`![Trading View icon (Alternative text)][ico]`

results in

![Trading View icon (Alternative text)][ico]

## References for reference-style links

Even though only the formatted references are visible here in the output, this text is also followed
by the following references with links in the style

`[Case-insensitive text/number reference from above]: Referenced link`

```
[Separate Trading View reference]: Here should be the link to the TradingView homepage "Trading view text-reference tooltip"
[1]: Here should be the link to the TradingView homepage "Trading view number-reference tooltip"
[Trading View, reference-style where the link text is the reference]: Here should be the link to the TradingView homepage "Trading view self-reference tooltip"

[ico]: Here should be the link to the favicon of the TradingView homepage "Trading View icon (reference)"
```

[Separate Trading View reference]: Here should be the link to the TradingView homepage "Trading view text-reference tooltip"
[1]: Here should be the link to the TradingView homepage "Trading view number-reference tooltip"
[Trading View, reference-style where the link text is the reference]: Here should be the link to the TradingView homepage "Trading view self-reference tooltip"

[ico]: Here should be the link to the favicon of the TradingView homepage "Trading View icon (reference)"
  Parameters:
    pLog (bool)

taskLists(pLog)
  Task lists.

Other Markdown implementations can also display task lists for list items like `- [ ]` respective `- [x]`.
This can only be simulated by inline code `` ´[ ]` ``.
Make sure to either add a line-break `\` at the end of the line or a new paragraph by a blank line.

### Task lists

`[x]` Finish library

`[ ]` Finish library
  Parameters:
    pLog (bool)

escapeMd(pLog)
  Escaping Markdown syntax

To write and display Markdown syntax in regular text, we have to escape it. This can be done
by adding `\` before the Markdown syntax. If the Markdown syntax consists of more than one character
in some cases also the character of function [zeroWidthSpace()] can be helpful if a command consists of
more than one character if it is placed between the separate characters of the command.
  Parameters:
    pLog (bool)

test()
  Calls all functions of above script.