Skip to content

Commit b9daafb

Browse files
adityapatwardhanadityapatwardhan
committed
Addressed comments
1 parent 03196ba commit b9daafb

File tree

2 files changed

+61
-24
lines changed

2 files changed

+61
-24
lines changed

‎1-Draft/RFCNNNN-Native-Markdown-Rendering.md renamed to ‎2-Draft-Accepted/RFCNNNN-Native-Markdown-Rendering.md

Lines changed: 61 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ RFC:
33
Author: Aditya Patwardhan
44
Status: Draft
55
SupercededBy:
6-
Version: 0.1
6+
Version: 0.2
77
Area: Formatting and Output
88
Comments Due: 03/26/2018
99
Plan to implement: Yes
@@ -20,29 +20,65 @@ There is no easy way in PowerShell to visualize a markdown document on console.
2020

2121
## Specification
2222

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.
23+
This RFC proposes to use `VT100` escape sequences to render markdown content.
24+
`ConvertFrom-Markdown` cmdlet as part of `Microsoft.PowerShell.Utility` PowerShell module would consume a string or a file path and output a PSObject containing three properties, `Tokens`, `Html`, `VT100EncodedString`.
25+
The `Tokens` property has the AST for the markdown document from `markdig`.
26+
The `Html` property has the markdown document converted to `HTML`.
27+
The `VT100EncodedString` property has the markdown documented with `VT100` escape sequences.
28+
By default, the `Tokens`and `Html` properties will be populated.
29+
The `VT100EncodedString` property will be populated only when `-AsVT100EncodedString` is specified.
30+
2631
For converting strings to VT100 coded strings, we will be writing an extension to [markdig](https://github.com/lunet-io/markdig).
2732
The extension will insert VT100 escape sequences as appropriate.
2833

34+
### Specification for `ConvertFrom-Markdown`
35+
2936
```PowerShell
30-
ConvertFrom-Markdown [-Path] <string[]> -AsHTML -AsPlainText [<CommonParameters>]
3137
32-
ConvertFrom-Markdown -LiteralPath <string[]> -AsHTML -AsPlainText [<CommonParameters>]
38+
ConvertFrom-Markdown [-Path] <string[]> [-AsVT100EncodedString] [<CommonParameters>]
39+
40+
ConvertFrom-Markdown [-LiteralPath] <string[]> [-AsVT100EncodedString] [<CommonParameters>]
41+
42+
ConvertFrom-Markdown [-InputObject] <psobject> [-AsVT100EncodedString] [<CommonParameters>]
3343
34-
ConvertFrom-Markdown -InputObject <psobject> -AsHTML -AsPlainText [<CommonParameters>]
3544
```
3645

37-
### Parameters
46+
#### Parameters
3847

3948
- **Path** : Accepts an array of file paths with markdown content.
4049
- **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.
50+
- **InputObject** : Accepts an InputObject of `System.IO.FileInfo`, `string` type.
51+
- **AsVT100EncodedString** : When selected, the `VT100EncodedString` property is populated.
52+
53+
There will be support for changing the colors for various elements using the `Set-MarkdownOption` cmdlet. To retrieve the current settings `Get-MarkdownOption` cmdlet can be used.
54+
55+
### Specification for `Set-MarkdownOption`
56+
57+
```PowerShell
58+
59+
Set-MarkdownOption [-Header1Color <ConsoleColor>] [-Header2Color <ConsoleColor>] [-Header3Color <ConsoleColor>] [-Header4Color <ConsoleColor>] [-Header5Color <ConsoleColor>] [-Header6Color <ConsoleColor>] [-CodeBlockForegroundColor <ConsoleColor>] [-CodeBlockBackgroudColor <ConsoleColor>] [-ImageAltTextForegroundColor <ConsoleColor>] [-LinkForegroundColor <ConsoleColor>] [-ItalicsForegroundColor <ConsoleColor>] [<CommonParameters>]
60+
61+
Set-MarkdownOption [-Theme <MarkdownThemeType>] [<CommonParameters>]
4462
45-
The default output will be a string encoded with VT100 escape sequences.
63+
enum MarkdownThemeType
64+
{
65+
Dark
66+
Light
67+
}
68+
69+
```
70+
71+
The properties can be individually to customized the rendering on console.
72+
Dark will be the default theme.
73+
The individual colors for the dark theme are specified in the subsequent sections.
74+
75+
### Specification for `Get-MarkdownOption`
76+
77+
```PowerShell
78+
79+
Get-MarkdownOption [<CommonParameters>]
80+
81+
```
4682

4783
## Supported Markdown Elements
4884

@@ -60,16 +96,16 @@ These will be rendered as plain text.
6096

6197
VT100 escape sequences for headers are as follows:
6298

63-
| Element | Markdown | Rendered | Escape Sequences |
64-
|---------|-------------|----------|----------|
65-
| ATX Header 1 | ![](../assets/MarkdownRendering/Header1-MD.png) | ![](../assets/MarkdownRendering/Header1.png) | ESC[7mHeader 1ESC[0m |
66-
| ATX Header 2 | ![](../assets/MarkdownRendering/Header2-MD.png) | ![](../assets/MarkdownRendering/Header2.png) | ESC[4;93mHeader 1ESC[0m |
67-
| ATX Header 3 | ![](../assets/MarkdownRendering/Header3-MD.png) | ![](../assets/MarkdownRendering/Header3.png) | ESC[4;94mHeader 1ESC[0m |
68-
| ATX Header 4 | ![](../assets/MarkdownRendering/Header4-MD.png) | ![](../assets/MarkdownRendering/Header4.png) | ESC[4;95mHeader 1ESC[0m |
69-
| ATX Header 5 | ![](../assets/MarkdownRendering/Header5-MD.png) | ![](../assets/MarkdownRendering/Header5.png) | ESC[4;96mHeader 1ESC[0m |
70-
| ATX Header 6 | ![](../assets/MarkdownRendering/Header6-MD.png) | ![](../assets/MarkdownRendering/Header6.png) | ESC[4;97mHeader 1ESC[0m |
71-
| Setext Header 1 | ![](../assets/MarkdownRendering/SetextHeader1-MD.png) | ![](../assets/MarkdownRendering/SetextHeader1.png) | ESC[4;92mHeader 1ESC[0m |
72-
| Setext Header 2 | ![](../assets/MarkdownRendering/SetextHeader2-MD.png) | ![](../assets/MarkdownRendering/SetextHeader2.png) | ESC[7mHeader 1ESC[0m |
99+
| Element | Markdown | Rendered | Escape Sequences (Dark Theme) | Escape Sequences (Light Theme) |
100+
|---------|-------------|----------|----------|------------|
101+
| ATX Header 1 | ![](../assets/MarkdownRendering/Header1-MD.png) | ![](../assets/MarkdownRendering/Header1.png) | ESC[7mHeader 1ESC[0m | ESC[7mHeader 1ESC[0m |
102+
| ATX Header 2 | ![](../assets/MarkdownRendering/Header2-MD.png) | ![](../assets/MarkdownRendering/Header2.png) | ESC[4;93mHeader 1ESC[0m | ESC[4;33mHeader 1ESC[0m |
103+
| ATX Header 3 | ![](../assets/MarkdownRendering/Header3-MD.png) | ![](../assets/MarkdownRendering/Header3.png) | ESC[4;94mHeader 1ESC[0m | ESC[4;34mHeader 1ESC[0m |
104+
| ATX Header 4 | ![](../assets/MarkdownRendering/Header4-MD.png) | ![](../assets/MarkdownRendering/Header4.png) | ESC[4;95mHeader 1ESC[0m | ESC[4;35mHeader 1ESC[0m |
105+
| ATX Header 5 | ![](../assets/MarkdownRendering/Header5-MD.png) | ![](../assets/MarkdownRendering/Header5.png) | ESC[4;96mHeader 1ESC[0m | ESC[4;36mHeader 1ESC[0m |
106+
| ATX Header 6 | ![](../assets/MarkdownRendering/Header6-MD.png) | ![](../assets/MarkdownRendering/Header6.png) | ESC[4;97mHeader 1ESC[0m | ESC[4;30mHeader 1ESC[0m |
107+
| Setext Header 1 | ![](../assets/MarkdownRendering/SetextHeader1-MD.png) | ![](../assets/MarkdownRendering/SetextHeader1.png) | ESC[7mHeader 1ESC[0m | ESC[7mHeader 1ESC[0m |
108+
| Setext Header 2 | ![](../assets/MarkdownRendering/SetextHeader2-MD.png) | ![](../assets/MarkdownRendering/SetextHeader2.png) | ESC[4;93mHeader 1ESC[0m | ESC[4;33mHeader 1ESC[0m |
73109

74110
#### Code Blocks
75111

@@ -88,7 +124,7 @@ Span elements will have varying degree of support depending on element type.
88124

89125
#### Links
90126

91-
Links in paragraphs will keep the link label and append the link URL surrounded by parenthesis.
127+
Links in paragraphs will add double quotes around the link label and append the link URL surrounded by parenthesis.
92128
The link will be colored to differentiate from plain text.
93129

94130
| Markdown | Rendered | Escape Sequences |
@@ -138,4 +174,5 @@ The limitations of this approach are:
138174

139175
## Open Questions
140176

141-
- Investigate line wrapping behavior.
177+
- Investigate line wrapping behavior.
178+
- Investigate paging behavior.

‎assets/MarkdownRendering/Link.png

-396 Bytes
Loading

0 commit comments

Comments
 (0)