Markdown: The Pine Editor's Hidden Gem

22 lut 2023

💬 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 https://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

Pine Script®

Hope this helps. 👍