Hello,

Not sure this is the right place for this but I am using PSDocs along inside a powershell script to create a wiki page for azure devops.

It had been working fine but now out of nowhere it breaks when I run:

#region Create WIKI MarkDown Content
Write-Output "Creating mark down table for wiki"
Document 'Create-MarkdownTable' {
$date = Get-Date -UFormat "%d/%m/%Y %R"
Section Summary {
"This is the work item list for the build created: $date"
}
Section 'Work items'{
if ($InputObject.Count -lt 1)
{
"No work items are associated"
}
foreach($item in $InputObject)
{
"#$item"
}
}
}

Specifically:

Document 'Create-MarkdownTable' {

Has anything changed to PSDocs that may have caused this.

It throws an error of:

The property 'KeywordOutsideEngine' cannot be found on this object. Verify that the property exists.
At C:\Users\tom.gorton\Documents\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.psm1:389 char:10

•      Write-Error -Message $LocalizedHelp.KeywordOutsideEngine -Ca ...
  

•      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  

  • CategoryInfo : NotSpecified: (:) [], PropertyNotFoundException
  • FullyQualifiedErrorId : PropertyNotFoundStrict

I am not able to create a markdown file from a powershell get help command.
Can you provide an example for that?

I tried to generate a markdown from
Get-Help Format-Table

There was not output in the markdown. With your examples from Get-ChildItems ... it works.

Currently PSDocs supports input objects from the pipeline or -InputObject parameter.

Instead of doing a lot of pre-work to provide input objects to PSDocs, it would be much easier particularly in CI pipelines to provide a path to scan. For example Get-AzDocTemplateFile.

Required for #131

Currently external content can be included using the Include keyword, however the content is included as is.

While included content could be generated dynamically the common scenario of replacing tokens should be a standard feature.

This feature would be helpful for including badges.

Azure/PSDocs.Azure#30

Provide an example of using PSDocs with Docfx.

The keyword Include can be used to incorporate markdown fragments stored as separate files into the document.

Included files may include YAML metadata as front matter that is not valid within the body of the final document.

We need an option to ignore any front matter from included files.

If you can, please add full help information to your functions the most important ( Examples ) .

Description of the issue

When $PSDocs.Configuration.GetBoolOrDefault is used, the default value is always returned.

Expected behaviour

GetBoolOrDefault should return the configuration value when set or the default when the value is not set or is not a boolean.

Module in use and version:

• Module: PSDocs
• Version: 0.8.0-B2101011

Captured output from $PSVersionTable:

Name                           Value
----                           -----
PSVersion                      7.1.2
PSEdition                      Core
GitCommitId                    7.1.2
OS                             Microsoft Windows 10.0.19042
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Script blocks can be used with the Code keyword. While an info string can be included by default an info string is not set.

For PowerShell code (i.e. a script block) this should default to powershell.

Add an alias for using Markdown.Encoding on New-PSDocumentOption.

This option is normally set via -Encoding however is defined in configuration as Markdown.Encoding.

When importing PSDocs module, importing PSDocs.Format.ps1xml may fail if PSDocs.dll is blocked by Windows because it was downloaded from the PowerShell Gallery.

Import-Module : Errors occurred while loading the format data file:
C:\Program Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml, Error at XPath
/Configuration/ViewDefinitions/View[1] in file C:\Program
Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml: A node is missing from TableControl, ListControl,
WideControl, CustomControl.
C:\Program Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml, Error at XPath
/Configuration/ViewDefinitions/View[1]/TableControl/TableHeaders in file C:\Program
Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml: The column header definition is not valid; all
headers are discarded.

C:\Program Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml, Error at XPath
/Configuration/ViewDefinitions/View[1]/TableControl/TableHeaders/TableColumnHeader[1]/Label in file C:\Program
Files\WindowsPowerShell\Modules\PSDocs\0.7.0\PSDocs.Format.ps1xml: The resource PSDocs.Resources.ViewStrings in
assembly C:\PSDocs is not found.
At line:1 char:1
+ Import-Module PSDocs.Azure
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [Import-Module], RuntimeException
    + FullyQualifiedErrorId : FormatXmlUpdateException,Microsoft.PowerShell.Commands.ImportModuleCommand

We should add a note for troubleshooting this issue.

It can be fixed by using Unblock-File.

For example:

Get-ChildItem -Path 'C:\Program Files\WindowsPowerShell\Modules\PSDocs\' | Unblock-File;

See issue Azure/PSDocs.Azure#25.

I'd like to contribute some more example code and see if I can add to your repo. Would you be able to add it to Hacktoberfest please?

Thanks

https://hacktoberfest.digitalocean.com/hacktoberfest-update

Currently PSDocs doesn't have any way to format text for example italic or bold without preformatting text or mashing together string literals.

Add support for formatting of text with a Format block syntax, possibly also add regex selection of words.

Example syntax:

# Text on pipeline
'Some text to bold' | Format -Style Bold

# Text in block
Format -Style Bold,Italic {
  'Some text to bold and italicise'
}

# Apply formatting only to selected regex match
'Just bold the word bold only' | Format -Match 'bold' -Style Bold

See example of pester tests running but not reporting correctly.

https://ci.appveyor.com/project/BernieWhite/psdocs/build/0.3.0.63

Currently there is no real ability to dynamically change the name of the generated output file based on content within PSDocs. It needs to be decided before Invoke-PSDocument is called and passed as a parameter.

In the absence of -InstanceName the output file uses the name of the document definition.

This approach is inflexible at large scale because it generally requires a PowerShell wrapper block to be used.

For example:

# Scan for Azure template file recursively in the templates/ directory
Get-AzDocTemplateFile -Path templates/ | ForEach-Object {
    # Generate a standard name of the markdown file. i.e. <name>_<version>.md
    $template = Get-Item -Path $_.TemplateFile;
    $templateName = $template.Directory.Parent.Name;
    $version = $template.Directory.Name;
    $docName = "$($templateName)_$version";

    # Generate markdown
    Invoke-PSDocument -Module PSDocs.Azure -OutputPath out/docs/ -InputObject $template.FullName -InstanceName $docName;
}

Currently the current working path is used by default when -BaseDirectory is not specified.

For document definitions included in a module, base directory should instead default to the module directory instead of the current working path, as included resources would be packaged with the module.

I have been successfully generating markup files with this module, and started to render them with mkdocs or hugo. Yesterday I noticed that mkdocs wasn't able to render a file due to an encoding problem:

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xfc in position 991: invalid start byte

I took a look at the WriteDocumentContent function and I found that it doesn't specify the -Enconding parameter of Set-Content:

$content | Set-Content -Path $Path;

According to the documentation, the default value for the encoding of Set-Content is ASCII.

My current workaround for this is to specify the -PassThru parameter of Invoke-PSDocument and write the result to disk myself with the correct encoding:

Invoke-PSDocument -Name Test -PassThru | Out-File -FilePath ".\result\Test.md" -Encoding utf8

However, if the default behavior of Invoke-PSDocument is to write content to the disk, it should either be possible to specify the encoding, or the default encoding should not be ASCII

When PowerShell code within a document block generates an error it can be hard to identify what the issue is.

We can do better to bubble up the true cause of the error instead of PowerShell reporting that an error occurred in PSDocs functions.

PowerShell commands such as Select-Object and Format-Table support expressions in the -Property parameter that allow customisation of the columns that get exposed and allows columns to be projected into the resulting table.

Native support for a similar approach with Table would simplify document definition creation instead of having to pipe through Select-Object all the time.

Describe the bug

Script error hidden with exception handling issue.

Error output

Capture any error messages and or verbose messages with -Verbose.

The property 'PositionMessage' cannot be found on this object. Verify that the property exists.

Module in use and version (please complete the following information):

• Module: PSDocs
• Version 0.6.1

The default options file is ps-docs.yaml however documentation and some logic refers to .psdocs.yml. Update to fix these inconsistencies.

Currently PSDocs works on Windows and is tested against Windows PowerShell.

While Desired State Configuration and thus PSDocs.Dsc is only supported on Windows PowerShell currently, that shouldn't prevent core PSDocs which is a separate module from being used on other platforms and adding support for PowerShell Core.

• Update module code to support MacOS, Windows and Linux.
• Update CI pipeline to test against MacOS, Windows and Linux.
• Update module manifest to support cross platform deployment.
• Update dependencies documentation.

When a complex object is piped to the Code keyword, by default it will use the .ToString() method. In most cases this is not helpful, serializing as JSON would provide a more accurate representation of the object.

Description of the issue

If an empty title is specified using the Title keyword then a null binding exception is generated. The message should be clearer as to what the issue is.

To Reproduce

Steps to reproduce the issue:

Document 'example' {
    $a = $Null;
    Title $a;
}

Expected behaviour

Generate a warning instead specifying that the title is empty and will be skipped.

Error output

Cannot bind argument to parameter 'Text' because it is null.

Module in use and version:

• Module: PSDocs
• Version: 0.7.0

Captured output from $PSVersionTable:

Name                           Value
----                           -----
PSVersion                      7.1.0
PSEdition                      Core
GitCommitId                    7.1.0
OS                             Microsoft Windows 10.0.19042
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Publish a JSON schema for configuration options through ps-docs.yaml.

Describe the bug
Code blocks containing multiple lines don't output multiple lines. Adding an extra line inbetween doesn't work either.

To Reproduce

        Code powershell {
            # we need to escape \ in paths in markdown
            get-childitem $PSScriptRoot | Select-Object Name,@{Name="FullName";Expression={$_.FullName -replace '\\','\\'}} | Table
        }

and

        Code powershell {
            # we need to escape \ in paths in markdown

            get-childitem $PSScriptRoot | Select-Object Name,@{Name="FullName";Expression={$_.FullName -replace '\\','\\'}} | Table
        }

Expected behaviour
Output should be

\```powershell
# we need to escape \ in paths in markdown
get-childitem $PSScriptRoot | Select-Object Name,@{Name="FullName";Expression={$_.FullName -replace '\\','\\'}} | Table
\```

(without the \ at the start of the codefence, that's just for formatting this issue)

Error output
Actual output (for both) is

\```powershell
# we need to escape \ in paths in markdownget-childitem $PSScriptRoot | Select-Object Name,@{Name="FullName";Expression={$_.FullName -replace '\\','\\'}} | Table
\```

(without the \ at the start of the codefence, that's just for formatting this issue)

Module in use and version (please complete the following information):

• Module: PSDocs
• Version: 0.6.2

Additional context

To support making PSDocs cross-platform in the future. Move out PSDocs.Dsc into a separate repository.

Related to #59

The keyword Include can be used to incorporate markdown fragments stored as separate files into the document. Included files may include section headers.

PSDocs allows defining section headers that are structured hierarchically and the header level is automatically selected.

Included files are treated as raw input and do not follow the same structure.

Instead, header levels in included files should be automatically updated to align to hierarchical pattern, relative to their position in the document.

Add support for formatting items in a list.

For example:

Get-Service -Name Spooler | List -Property Name,DisplayName,Status;

And:

• Name : Spooler
• DisplayName : Print Spooler
• Status : Running

Add test coverage tracking.

Description of the issue

When using the Include keyword an exception is raised if the specified file does not exist. When using the -ErrorAction SilentlyContinue option of Include it is expected that the exception would silently continue but it does not.

To Reproduce

Steps to reproduce the issue:

Document 'IncludeOptional' {
    Include 'NotFile.md' -ErrorAction SilentlyContinue;
}

Expected behaviour

When -ErrorAction SilentlyContinue is specified, the cmdlet should silently continue.

Module in use and version:

• Module: PSDocs
• Version: 0.7.0

Captured output from $PSVersionTable:

Name                           Value
----                           -----
PSVersion                      7.1.1
PSEdition                      Core
GitCommitId                    7.1.1
OS                             Microsoft Windows 10.0.19042
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

PSDocs is able to generate markdown based on objects. When building documentation sites it is often additionally required to generate a table of contents (TOC) in markdown or yaml for processing by a publishing tool chain.

Currently the Get-PSDocumentHeader cmdlet can be used to extract yaml front matter from markdown and build a TOC however a more integrated solution would be preferred.

Potentially something like:

document 'Sample' {
   Section 'Header 1' {
      'Section text'
   }

   Index {
      # An indexing action
   }
}

Running Invoke-PSDocment with -PassThru doesn't result in any output.

Fix and expand unit tests to include tests for pass through object output.

Improve documentation for language keywords with examples and parameters:

• Section
• Title
• Code
• Table
• Warning
• Note
• Yaml

Documents can be built with PSDocs but they often require input to be supplied to Invoke-PSDocument.

When using PSDocs to generate dynamic documentation for projects that use a DevOps pipeline this is slightly more clunky then it should be.

Ideally we would target a directory i.e. . and then all the documentation would be built in the project.

The current suggestion is to discover documentation definitions to build based on a well known suffix such as .doc.ps1 following a similar pattern to Pester (.tests.ps1) or Invoke-Build (.build.ps1).

A typical documentation workflow can be simplified to:

# find .doc.ps1 recursively in current working path
Invoke-PSDocument;

# with alternative directories
Invoke-PSDocument './docs/';

# or
Invoke-PSDocument -Path '.\docs';

# or
Invoke-PSDocument -Path '.\docs\Sample.doc.ps1';

# or only a specific document
Invoke-PSDocument -Name 'Sample';

Describe the bug

When BlockQuote is used, a trailing line break is not added after the block quote content.

Expected behaviour

A line break should be added after each block quote.

Module in use and version:

• Module: PSDocs
• Version: 0.7.0-B2008035

When processing objects with a Document definition, different objects may be passed in. A Document definition is specific to an object with certain properties and type. Passing in a incompatible object would only fail in most circumstances.

Therefore we need to selectively process certain objects with a Document definition.

Currently PSDocs can generate localized content, however built-in support requires using external include files with the Include keyword.

Ideally we should be able to pull content from a localized .psd1 file.

This will be implemented by a $LocalizedData variable that read localized strings based on current culture.

We should be able to read a objects from a file instead of only from the pipeline.

If a file is a standard format such as JSON or YAML we should be able to automatically deserialize the objects.

Add support for generating documents in OpenXml aka Word as an alternative to only using markdown.

We can do better formatting tables by using spaces to align columns.

Also trailing and leading pipes should be optional.

Example:

|Name|PSIsContainer|
| --- | --- |
|PerfLogs|True|
|Program Files|True|
|Program Files (x86)|True|
|Users|True|
|Windows|True|

| Name                      | PSIsContainer |
| ----                      | ------------- |
| PerfLogs                  | True          |

Output configuration can be specified by using -Culture and -OutputPath parameters. When running from a pipeline these options would be easier to set in configuration.

Hi,

I noticed that if I convert an object that has a string with a line break in one of its properties, the line break is not escaped when converting it to a md table.

$HasNewline = @"
One, Two,
Three
"@

$Object = [PsCustomObject] @{

    String1 = "1 2 3 4 5"
    String2 = $HasNewline
    String3 = "6 7 8 9 0"

}

Document Sample {

    $Object | Table

}

Invoke-PSDocument -Name 'Sample' -PassThru

The result is

|String1|String2|String3|
| --- | --- | --- |
|1 2 3 4 5|One, Two,
Three|6 7 8 9 0|

Which breaks the table if I render the markdown as HTML. The new lines should be escaped with <br> or \

Describe the bug
When using the Invoke-PSDocument command, paths with white space are causing an error where the first part of the path is being interpreted as a cmdlet/function etc.

To Reproduce
Invoke-PSDocument -Path "C:\Users\username\OneDrive - Personal\subfolder" ...

Expected behaviour
The script should execute as normal, creating the markdown docs

Error output

VERBOSE: [Invoke-PSDocument]::BEGIN

VERBOSE: [Doc] -- Getting document definitions from: C:\Users\CraigPort\OneDrive - Company\Projects\template.doc.ps1

VERBOSE: Attempting to read: .\psdocs.yml

VERBOSE: [Doc] -- InputObject is null

VERBOSE: [Doc] -- Processing: C:\Users\CraigPort\OneDrive - Company\Projects\template.doc.ps1

Invoke-PSDocument : The term 'C:\Users\CraigPort\OneDrive' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the

path is correct and try again.

At line:1 char:1

+ Invoke-PSDocument -Path 'C:\Users\CraigPort\OneDrive - Company\Projec ...

+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    + CategoryInfo          : InvalidOperation: (:) [Write-Error], InvokeDocumentException

    + FullyQualifiedErrorId : CommandNotFoundException,Invoke-PSDocument


VERBOSE: [Invoke-PSDocument]::END

Module in use and version (please complete the following information):

• Module: PSDocs
• Version 0.6.3

Additional context
Add any other context about the problem here.

Describe the bug

When using the Metadata keyword`, the value passed may be null. When null is passed an exception is raised.

To Reproduce

Steps to reproduce the behaviour.

Document 'Example' {
    Metadata $Null
}

Expected behaviour

Metadata should gracefully handle null data by not adding any metadata and supressing the exception by default.

Error output

Invoke-PSDocument : Cannot bind argument to parameter 'Body' because it is null.
At line:1 char:18
+ ... s.Info | %{ Invoke-PSDocument -Path .\RuleHelp.Doc.ps1 -OutputPath .\ ...
+                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (:) [Write-Error], InvokeDocumentException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Metadata,Invoke-PSDocument

Module in use and version:

• Module: PSDocs
• Version 0.6.1

Description of the issue

When using table with defined property names e.g. Table -Property RuleName, Message if one of the columns doesn't exist on the pipeline object an exception is raised and the document is not processed further.

To Reproduce

Steps to reproduce the behaviour:

Document 'TableTest' {
    [PSCustomObject]@{ Name = 'Test' } | Table -Property Name, Value
}

Invoke-PSDocument -Name 'TableTest';

Expected behaviour

The document should be generated with an empty value in the column, replicating behaviour of PowerShell Format-Table -Property Name, Value

Error output

Invoke-PSDocument : Object reference not set to an instance of an object.

Module in use and version

• Module: PSDocs
• Version: 0.6.0

Document definitions are reusable artifacts, however it is not easy to share and distribute them currently. To distribute, document definitions need to be packaged and transferred. PowerShell modules already provide these features through PowerShellGet so it makes sense for PSDocs to support this as a feature.

Sections should only be generated when there is content within them by default. An option should still exist for force generation of sections regardless.

For example, an empty section in the example below should not be generated.

document Sample {
   Section 'Empty section' {

   }
}

Example use of -Force to force the generation of an empty section.

document Sample {
   Section 'Empty section' -Force {

   }
}

Provide a way to bind an input object to extract out the name of the object.

Once the name of the object is extracted, then the name can be used for the default document name instead if relying on InstanceName which does not work across many objects at scale.

Currently PSDocs doesn't provide a way to configure document generation outside of engine features.

It is likely that a document definition may want to define one or more custom configurable options that can be specified.