|
| 1 | +--- |
| 2 | +RFC: |
| 3 | +Author: Aditya Patwardhan |
| 4 | +Status: Draft |
| 5 | +SupercededBy: |
| 6 | +Version: 0.1 |
| 7 | +Area: Formatting and Output |
| 8 | +Comments Due: 03/26/2018 |
| 9 | +Plan to implement: Yes |
| 10 | +--- |
| 11 | + |
| 12 | +# Native Markdown Rendering |
| 13 | + |
| 14 | +Render markdown content on console to improve readability. |
| 15 | + |
| 16 | +## Motivation |
| 17 | + |
| 18 | +Markdown is a common authoring format used by the community. |
| 19 | +There is no easy way in PowerShell to visualize a markdown document on console. |
| 20 | + |
| 21 | +## Specification |
| 22 | + |
| 23 | +This RFC proposes to use VT100 escape sequences to render markdown content. |
| 24 | +`ConvertFrom-Markdown` cmdlet as part of `Microsoft.PowerShell.MarkdownRender` PowerShell module would consume a string or a file path and output a VT100 encoded string. |
| 25 | +Optionally, the output can be formatted as HTML. |
| 26 | +For converting strings to VT100 coded strings, we will be writing an extension to [markdig](https://github.com/lunet-io/markdig). |
| 27 | +The extension will insert VT100 escape sequences as appropriate. |
| 28 | + |
| 29 | +```PowerShell |
| 30 | +ConvertFrom-Markdown [-Path] <string[]> -AsHTML -AsPlainText [<CommonParameters>] |
| 31 | +
|
| 32 | +ConvertFrom-Markdown -LiteralPath <string[]> -AsHTML -AsPlainText [<CommonParameters>] |
| 33 | +
|
| 34 | +ConvertFrom-Markdown -InputObject <psobject> -AsHTML -AsPlainText [<CommonParameters>] |
| 35 | +``` |
| 36 | + |
| 37 | +### Parameters |
| 38 | + |
| 39 | +- **Path** : Accepts an array of file paths with markdown content. |
| 40 | +- **LiteralPath** : Accepts an array of literal paths with markdown content. |
| 41 | +- **InputObject** : Accepts an InputObject of `System.IO.FileSystemInfo`, `string` type. |
| 42 | +- **AsHTML** : When selected, the output will be HTML. |
| 43 | +- **AsPlainText** : When selected, the output will be plain text. |
| 44 | + |
| 45 | +The default output will be a string encoded with VT100 escape sequences. |
| 46 | + |
| 47 | +## Supported Markdown Elements |
| 48 | + |
| 49 | +We will be supporting a limited set of markdown elements in the initial version. |
| 50 | + |
| 51 | +### Block Elements |
| 52 | + |
| 53 | +The block elements include paragraphs and line breaks, headers, block quotes, code blocks and horizontal rules. |
| 54 | + |
| 55 | +#### Paragraphs and line breaks |
| 56 | + |
| 57 | +These will be rendered as plain text. |
| 58 | + |
| 59 | +#### Headers |
| 60 | + |
| 61 | +VT100 escape sequences for headers are as follows: |
| 62 | + |
| 63 | +| Element | Markdown | Rendered | Escape Sequences | |
| 64 | +|---------|-------------|----------|----------| |
| 65 | +| ATX Header 1 |  |  | ESC[7mHeader 1ESC[0m | |
| 66 | +| ATX Header 2 |  |  | ESC[4;93mHeader 1ESC[0m | |
| 67 | +| ATX Header 3 |  |  | ESC[4;94mHeader 1ESC[0m | |
| 68 | +| ATX Header 4 |  |  | ESC[4;95mHeader 1ESC[0m | |
| 69 | +| ATX Header 5 |  |  | ESC[4;96mHeader 1ESC[0m | |
| 70 | +| ATX Header 6 |  |  | ESC[4;97mHeader 1ESC[0m | |
| 71 | +| Setext Header 1 |  |  | ESC[4;92mHeader 1ESC[0m | |
| 72 | +| Setext Header 2 |  |  | ESC[7mHeader 1ESC[0m | |
| 73 | + |
| 74 | +#### Code Blocks |
| 75 | + |
| 76 | +Code blocks will be rendered with a lighter background color and a dark foreground text. |
| 77 | +Background color will be applied for the console width. |
| 78 | +No syntax highlighting will be done. |
| 79 | +`ESC[500@` is used to have sufficiently wide background color. |
| 80 | + |
| 81 | +| Markdown | Rendered | Escape Sequences | |
| 82 | +|-------------|----------|----------| |
| 83 | +|  |  | ESC[48;2;155;155;155;38;2;30;30;30mTextESC[500@ESC[0m | |
| 84 | + |
| 85 | +### Span Elements |
| 86 | + |
| 87 | +Span elements will have varying degree of support depending on element type. |
| 88 | + |
| 89 | +#### Links |
| 90 | + |
| 91 | +Links in paragraphs will keep the link label and append the link URL surrounded by parenthesis. |
| 92 | +The link will be colored to differentiate from plain text. |
| 93 | + |
| 94 | +| Markdown | Rendered | Escape Sequences | |
| 95 | +|----------|----------|-------------| |
| 96 | +|  |  | ESC[4;34m( )ESC[0m | |
| 97 | + |
| 98 | +If the links are part of a container like a pipe table, block quote or list; then just the link label will be shown. |
| 99 | + |
| 100 | +#### Emphasis |
| 101 | + |
| 102 | +Emphasis will be rendered using escape sequence `ESC[1mBold TextESC[0m` and `ESC[36mItalics TextESC[0m` for bold text and italics text respectively. |
| 103 | + |
| 104 | +| Element | Markdown | Rendered | Escape Sequences | |
| 105 | +|---------|-------------|----------|----------| |
| 106 | +| Bold |  |  | ESC[1mBold TextESC[0m | |
| 107 | +| Italics |  | | ESC[36mItalics TextESC[0m | |
| 108 | + |
| 109 | +#### Code |
| 110 | + |
| 111 | +Inline code elements will be rendered similar to code blocks, with the exception on background color to not extend beyond the markdown element. |
| 112 | + |
| 113 | +| Markdown | Rendered | Escape Sequences | |
| 114 | +|-------------|----------|----------| |
| 115 | +|  |  | ESC[48;2;155;155;155;38;2;30;30;30mTextESC[0m`| |
| 116 | + |
| 117 | +#### Images |
| 118 | + |
| 119 | +The alt-text of the image will be surrounded by `[` and `]` and colorized to differentiate from plain text. |
| 120 | +Escape code for images alt-text |
| 121 | + |
| 122 | +| Markdown | Rendered | Escape Sequences | |
| 123 | +|-------------|----------|----------| |
| 124 | +|  |  | ESC[33m[alt-text]ESC[0m | |
| 125 | + |
| 126 | +## Future Work |
| 127 | + |
| 128 | +`Paragraphs and Line Breaks`, `Block Quotes`, `Lists`, `Horizontal Rules`, `Pipe tables` and `HTML code` will be considered for future versions and rendered as plain text in this version. |
| 129 | + |
| 130 | +## Alternate Proposals and Considerations |
| 131 | + |
| 132 | +Introduce a new sigil to define a markdown string. |
| 133 | +This would be later rendered using formating files. |
| 134 | +The limitations of this approach are: |
| 135 | + |
| 136 | +1. Can be used only in script. |
| 137 | +2. Adds a new dependency of `markdig` to `System.Management.Automation`. |
| 138 | + |
| 139 | +## Open Questions |
| 140 | + |
| 141 | +- Investigate line wrapping behavior. |
0 commit comments