Skip to content

Commit 728d9cc

Browse files
BernieWhitevors
BernieWhite
authored and
vors
committed
Add PowerShell language info-string to code blocks issue #318 (#327)
* Update to preserve code fence info-string #318 * Add powershell info-string to code blocks #294
1 parent 3ff5472 commit 728d9cc

17 files changed

+151
-67
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@ CHANGELOG
44
## Not released
55

66
* Clean up trailing whitespace during markdown generation [#225](https://github.com/PowerShell/platyPS/issues/225)
7-
* Preserve line breaks after headers when Update-MarkdownHelp is used [#319](https://github.com/PowerShell/platyPS/issues/319)
7+
* Preserve line breaks after headers when `Update-MarkdownHelp` is used [#319](https://github.com/PowerShell/platyPS/issues/319)
88
* MAML generation now pads example titles with dash (-) to improve readability [#119](https://github.com/PowerShell/platyPS/issues/119)
9-
* Fixed issue with New-MarkdownHelp preventing CommonParameter being added for advanced functions and workflows [#223](https://github.com/PowerShell/platyPS/issues/223) [#253](https://github.com/PowerShell/platyPS/issues/253)
9+
* Fixed issue with `New-MarkdownHelp` preventing CommonParameter being added for advanced functions and workflows [#223](https://github.com/PowerShell/platyPS/issues/223) [#253](https://github.com/PowerShell/platyPS/issues/253)
10+
* Fixed issue with `Update-MarkdownHelp` removing named info-string from code fence [#318](https://github.com/PowerShell/platyPS/issues/318)
1011

1112
## 0.8.3
1213

‎src/Markdown.MAML/Markdown.MAML.csproj

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@
5050
</Reference>
5151
</ItemGroup>
5252
<ItemGroup>
53+
<Compile Include="Model\MAML\MamlCodeBlock.cs" />
5354
<Compile Include="Model\MAML\MamlExample.cs" />
5455
<Compile Include="Model\MAML\MamlInputOutput.cs" />
5556
<Compile Include="Model\MAML\MamlLink.cs" />

‎src/Markdown.MAML/Model/MAML/MamlCodeBlock.cs

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
using System;
2+
using System.Collections.Generic;
3+
using System.Linq;
4+
using System.Text;
5+
using System.Threading.Tasks;
6+
7+
namespace Markdown.MAML.Model.MAML
8+
{
9+
/// <summary>
10+
/// A section of code such as PowerShell commands or command output.
11+
/// </summary>
12+
public sealed class MamlCodeBlock
13+
{
14+
public MamlCodeBlock(string text, string languageMoniker = null)
15+
{
16+
Text = text;
17+
LanguageMoniker = languageMoniker ?? string.Empty;
18+
}
19+
20+
/// <summary>
21+
/// An optional language or info-string. If no language string is suppled plain text is assumed.
22+
/// For more information see: http://spec.commonmark.org/0.28/#info-string
23+
/// </summary>
24+
public string LanguageMoniker { get; private set; }
25+
26+
/// <summary>
27+
/// The text of the code block.
28+
/// </summary>
29+
public string Text { get; private set; }
30+
}
31+
}

‎src/Markdown.MAML/Model/MAML/MamlExample.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ namespace Markdown.MAML.Model.MAML
1010
public class MamlExample
1111
{
1212
public string Title { get; set; }
13-
public string Code { get; set; }
13+
public MamlCodeBlock[] Code { get; set; }
1414
public string Remarks { get; set; }
1515
public string Introduction { get; set; }
1616

‎src/Markdown.MAML/Renderer/MamlRenderer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ private static XElement CreateExample(MamlExample example)
165165
{
166166
return new XElement(commandNS + "example",
167167
new XElement(mamlNS + "title", PadExampleTitle(example.Title)),
168-
new XElement(devNS + "code", example.Code),
168+
new XElement(devNS + "code", string.Join("\r\n\r\n", example.Code.Select(block => block.Text))),
169169
new XElement(devNS + "remarks", GenerateParagraphs(example.Remarks)));
170170
}
171171

‎src/Markdown.MAML/Renderer/Markdownv2Renderer.cs

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,6 @@ public class MarkdownV2Renderer
2222

2323
private ParserMode _mode;
2424

25-
private int _maxLineWidth { get; set; }
26-
2725
public int MaxSyntaxWidth { get; private set; }
2826

2927
/// <summary>
@@ -39,11 +37,6 @@ public MarkdownV2Renderer(ParserMode mode, int maxSyntaxWidth)
3937
this._mode = mode;
4038
}
4139

42-
public MarkdownV2Renderer(int maxLineWidth)
43-
{
44-
_maxLineWidth = maxLineWidth;
45-
}
46-
4740
public string MamlModelToString(MamlCommand mamlCommand, bool skipYamlHeader)
4841
{
4942
return MamlModelToString(mamlCommand, null, skipYamlHeader);
@@ -354,7 +347,10 @@ private void AddExamples(MamlCommand command)
354347

355348
if (example.Code != null)
356349
{
357-
AddCodeSnippet(example.Code);
350+
for (var i = 0; i < example.Code.Length; i++)
351+
{
352+
AddCodeSnippet(example.Code[i].Text, example.Code[i].LanguageMoniker);
353+
}
358354
}
359355

360356
if (!string.IsNullOrEmpty(example.Remarks))
@@ -604,9 +600,7 @@ public static string GetEscapedMarkdownText(string text)
604600
// per https://github.com/PowerShell/platyPS/issues/121 we don't perform escaping for () in markdown renderer, but we do in the parser
605601
//.Replace(@"(", @"\(")
606602
//.Replace(@")", @"\)")
607-
.Replace(@"`", @"\`")
608-
609-
;
603+
.Replace(@"`", @"\`");
610604
}
611605
}
612606
}

‎src/Markdown.MAML/Renderer/YamlRenderer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ private static YamlExample CreateExample(MamlExample mamlExample)
4949
{
5050
Name = mamlExample.Title,
5151
PreCode = mamlExample.Introduction,
52-
Code = mamlExample.Code,
52+
Code = string.Join("\r\n\r\n", mamlExample.Code.Select(block => block.Text)),
5353
PostCode = mamlExample.Remarks
5454
};
5555
}

‎src/Markdown.MAML/Transformer/ModelTransformerBase.cs

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
using Markdown.MAML.Model.MAML;
77
using System.Management.Automation;
88
using Markdown.MAML.Parser;
9+
using System.Text.RegularExpressions;
910

1011
namespace Markdown.MAML.Transformer
1112
{
@@ -177,19 +178,19 @@ protected MamlExample ExampleRule()
177178
};
178179
example.Introduction = GetTextFromParagraphNode(ParagraphNodeRule());
179180
example.FormatOption = headingNode.FormatOption;
180-
CodeBlockNode codeBlock;
181-
while ((codeBlock = CodeBlockRule()) != null)
181+
CodeBlockNode codeBlockNode;
182+
List<MamlCodeBlock> codeBlocks = new List<MamlCodeBlock>();
183+
184+
while ((codeBlockNode = CodeBlockRule()) != null)
182185
{
183-
if (example.Code == null)
184-
{
185-
example.Code = codeBlock.Text;
186-
}
187-
else
188-
{
189-
example.Code += "\r\n\r\n" + codeBlock.Text;
190-
}
186+
codeBlocks.Add(new MamlCodeBlock(
187+
codeBlockNode.Text,
188+
codeBlockNode.LanguageMoniker
189+
));
191190
}
192191

192+
example.Code = codeBlocks.ToArray();
193+
193194
example.Remarks = GetTextFromParagraphNode(ParagraphNodeRule());
194195

195196
return example;

‎src/platyPS/platyPS.psm1

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -134,7 +134,9 @@ function New-MarkdownHelp
134134
$MamlExampleObject = New-Object -TypeName Markdown.MAML.Model.MAML.MamlExample
135135

136136
$MamlExampleObject.Title = 'Example 1'
137-
$MamlExampleObject.Code = 'PS C:\> {{ Add example code here }}'
137+
$MamlExampleObject.Code = @(
138+
New-Object -TypeName Markdown.MAML.Model.MAML.MamlCodeBlock ('PS C:\> {{ Add example code here }}', 'powershell')
139+
)
138140
$MamlExampleObject.Remarks = '{{ Add example description here }}'
139141

140142
$MamlCommandObject.Examples.Add($MamlExampleObject)
@@ -202,7 +204,7 @@ function New-MarkdownHelp
202204
$a['Module'] = $module
203205
}
204206

205-
$helpFileName = GetHelpFileName (Get-Command @a)
207+
$helpFileName = GetHelpFileName (Get-Command @a)
206208
}
207209

208210
Write-Verbose "Maml things module is: $($mamlObject.ModuleName)"
@@ -2500,7 +2502,9 @@ function ConvertPsObjectsToMamlModel
25002502

25012503
$MamlExampleObject.Introduction = $Example.introduction
25022504
$MamlExampleObject.Title = $Example.title
2503-
$MamlExampleObject.Code = $Example.code
2505+
$MamlExampleObject.Code = @(
2506+
New-Object -TypeName Markdown.MAML.Model.MAML.MamlCodeBlock ($Example.code, '')
2507+
)
25042508

25052509
$RemarkText = $Example.remarks.text | AddLineBreaksForParagraphs
25062510

‎test/Markdown.MAML.Test/EndToEnd/EndToEndTests.cs

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -92,24 +92,28 @@ When calling Update-MarkdownHelp line breaks should be preserved.
9292
## EXAMPLES
9393
9494
### Example 1: With no line break or description
95+
```powershell
96+
PS C:\> Write-Host 'This is output.'
9597
```
96-
PS C:\> Update-MarkdownHelp
98+
99+
```
100+
This is output.
97101
```
98102
99103
This is example 1 remark.
100104
101105
### Example 2: With no line break
102106
This is an example description.
103107
104-
```
108+
```powershell
105109
PS C:\> Update-MarkdownHelp
106110
```
107111
108112
This is example 2 remark.
109113
110114
### Example 3: With line break and no description
111115
112-
```
116+
```powershell
113117
PS C:\> Update-MarkdownHelp
114118
```
115119
@@ -119,10 +123,14 @@ This is example 3 remark.
119123
120124
This is an example description.
121125
122-
```
126+
```preserve
123127
PS C:\> Update-MarkdownHelp
124128
```
125129
130+
```text
131+
Output
132+
```
133+
126134
This is example 4 remark.
127135
128136
## PARAMETERS

0 commit comments

Comments
 (0)