MarkdownUtilsLibrary "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 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) 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)
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
` (Here should be the link to the TradingView homepage)`\
results in (Here should be the link to the TradingView homepage)
` (Here should be the link to the TradingView homepage "Trading View tooltip")`\
results in (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.
` `\
results in .
` `\
results in .
` `\
results in .
` (../tradingview/scripts/readme)`\
results in (../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
`` |
`support@tradingview.com` | support@tradingview.com
`` |
## Images
We can display gif, jp(e)g and png files in our documentation, if we add `!` before a link.
### Inline-style:
`! (Here should be the link to the favicon of the TradingView homepage "Trading View icon")`
results in
! (Here should be the link to the favicon of the TradingView homepage "Trading View icon")\
### Reference-style:
`! `
results in
!
## 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
` : Referenced link`
```
: Here should be the link to the TradingView homepage "Trading view text-reference tooltip"
: Here should be the link to the TradingView homepage "Trading view number-reference tooltip"
: Here should be the link to the TradingView homepage "Trading view self-reference tooltip"
: Here should be the link to the favicon of the TradingView homepage "Trading View icon (reference)"
```
: Here should be the link to the TradingView homepage "Trading view text-reference tooltip"
: Here should be the link to the TradingView homepage "Trading view number-reference tooltip"
: Here should be the link to the TradingView homepage "Trading view self-reference tooltip"
: 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 `- `.
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
` ` 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 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.
Markdown
Markdown: The Pine Editor's Hidden Gem💬 Markdown, a markup language
Markdown is a portable, lightweight markup language that can be used for everything whether you're building a website, documentation, or even presentations.
Platforms like Discord, Reddit, and GitHub support Markdown and is the widely go-to option for text formatting due to its simplicity. Pine Script is a language that also utilizes Markdown, specifically in the Pine Editor where it can really be used to some extent.
Since the release of libraries, user-defined types, and methods, Pine Script is entering an age where developers will be highly dependent on libraries due to the capabilities Pine has inherited recently. It would be no surprise if a few people got together and took their time to thoroughly develop an entire project/library centered around improving Pine Script's built-in functions and providing developers with easier ways of achieving things than they thought they could.
As you're all aware, hovering over functions (and more) in the editor pops up a prompt that specifies the parameters, types, and what the function returns. Pine Script uses Markdown for that, so I figured we could go ahead and push that feature to its limits and see what we can do.
Today we'll go over how we can utilize Markdown in Pine Script, and how you can make your library's built-in functions stand out more than they did previously.
For more information, visit www.markdownguide.org
📕 General Notes
Markdown syntax only works on functions and methods.
Using arrays as parameters as of 2/21/2023 breaks the Markdown system.
The prompt window holds a max of 166 characters on one line before overflowing.
There is no limit on how long the prompt window can be.
🔽 Getting Started 🔽
▶️ Headings
If you have experience in HTML, Markdown, or even Microsoft Word then you already have a grasp of how headings work and look.
To simplify it, headings make the given text either massive or tiny depending on how many number symbols are provided.
When defining headings, you must have a space between the number (#) symbol, and the text. This is typical syntax throughout the language.
Pine Script uses bold text by applying (**) for their titles on their built-ins (e.g. @returns) but you could also use heading level 4 (####) and have it look the same.
▶️ Paragraphs & Line Breaks
You may want to provide extensive details and examples relating to one function, in this case, you could create line breaks. Creating line breaks skips to the next line so you can keep things organized as a result.
To achieve a valid line break and create a new paragraph, you must end the line with two or more spaces.
If you want to have an empty line in between, apply a backslash (\).
Backslashes (\) are generally not recommended for every line break. In this case, I only recommend using them for empty lines.
▶️ Text Formatting
Markdown provides text formatting such as bold, italics, and strikethrough.
For bolding text, you can apply open and close (**) or (__).
For italicizing text, you can apply open and close (*) or (_).
For bolding and italicizing text, you can apply open and close (***) or (___).
For s̶t̶r̶i̶k̶e̶t̶h̶r̶o̶u̶g̶h̶, you need to apply open and close (~~).
This was mentioned in the Headers section, but Pine Script's main titles (e.g. @returns or @syntax) use bold (**) by default.
▶️ Blockquotes
Blockquotes in Pine Script can be visualized as a built-in indentation system.
They are declared using greater than (>) and everything will be auto-aligned and indented until closed.
By convention you generally want to include the greater than (>) on every line that's included in the block quote. Even when not needed.
If you would like to indent even more (nested blockquotes), you can apply multiple greater than symbols (>). For example, (>>)
Blockquotes can be closed by ending the next line with only one greater than (>) symbol, or by using a horizontal rule.
▶️ Horizontal Rules
Horizontal rules in Pine Script are what you see at the very top of the prompt in built-ins.
When hovering, you can see the top of the prompt provides a line, and we can actually reproduce these lines.
These are extremely useful for separating information into their own parts and are accessed by applying 3 underscores (___), or 3 asterisks (***).
Horizontal rules were mentioned above, when we were discussing block quotes. These can also be used to close blockquotes as well.
Horizontal rules require a minimum of 3 underscores (___) or 3 asterisks (***).
▶️ Lists
Lists give us a way to structure data in a somewhat neat way. There are multiple ways to start a list, such as
1. First Item (number followed by a period)
- First Item (dash)
+ First Item (plus sign)
* First Item (asterisk)
Using number-based lists provide an ordered list, whereas using (-), (+), or (*) will provide an unordered list (bullet points).
If you want to begin an unordered list with a number that ends with a period, you must use an escape sequence (\) after the number.
Standard indentation (tab-width) list detection isn't supported, so to nest lists you have to use blockquotes (>) which may not look as appealing.
▶️ Code Blocks
Using code blocks allows you to write actual Pine Script code inside the prompt.
It's a game changer that can potentially help people understand how to execute functions quickly.
To use code blocks, apply three 3 open and close backquotes (```). Built-in's use (```pine) but there's no difference when we apply it.
Considering that tab-width indentation isn't detected properly, we can make use of the blockquotes mentioned above.
▶️ Denotation
Denoting can also be seen as highlighting a background layer behind text. They're basically code blocks, but without the "block".
Similar to how code blocks work, we apply one backquote open and close (`).
Make sure to only use this on important keywords. There really isn't a conventional way of applying this.
It's up to you to decide what people should have their eyes tracked onto when they hover over your functions.
If needed, look at how Pine Script's built-in variables and functions utilize this.
▶️ Tables
Tables are possible in Markdown, although they may look a bit different in the Pine Editor.
They are made by separating text with vertical bars (|).
The headers are detected when there is a minimum of one hyphen (-) below them.
You can align text by using a colon as I do in the photo. Hyphens must be connected to the colon in order to display correctly.
Tables aren't ideal to use in the editor but are there if anyone wants to give it a go.
▶️ Links & Images
Markdown supports images and hyperlinks, which means we can also do that here in the Pine Editor. Cool right?
If you want to create a hyperlink, surround the displayed text in open and close brackets .
If you want to load a photo into your prompt, it's the same syntax as the hyperlink, except it uses a (!)
See syntax list below.
Here are realistic usage examples. (Snippets from code below)
These follow the same syntax as the built-ins.
I'm not using horizontal rules here, but it's entirely up to you.
▶️ Syntax List
Headings
Level 1: #
Level 2: ##
Level 3: ###
Level 4: ####
Level 5: #####
Level 6: ######
Line Breaks
Text (two spaces)
Text\ (backslash)
Text Formatting
Bold (**)
Italic (**)
Strikethrough (~~)
Blockquotes
Indent (>)
Double Indent (>>)
Triple Indent (>>>) and so on.
Horizontal Rules
(___) or (***)
Lists
Ordered List (1.)
Unordered List (-) or (+) or (*)
Code Blocks
(```) or (```pine)
Denotation
(`)
Tables
(|) and (-) and (:)
Hyperlinks
(URL)
Images
! (URL)
Hope this helps. 👍
