alt3 / docusaurus.powershell Goto Github PK

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://docusaurus-powershell.netlify.com/

View results

Use search filter ─BROKEN─ to highlight failures

Following the discussion on this pr and noticing that this is still persisting https://pester.dev/docs/commands/New-PesterConfiguration#description it seems like there is still a regex that is a little too eager to help.

Unless the Pester 5.4.0 docs are not using the latest Alt3.Docusaurus.Powershell (which I cannot seem to tell what version it is using) then there may still be something amiss with that part of the generation.

PlatyPS is not handling multi-line examples correctly like can be seen on this screenshot taken from https://deploy-preview-1--pester-docs.netlify.com/docs/commands/Add-AssertionOperator

Code

### EXAMPLE 1
\`\`\`powershell
function BeAwesome($ActualValue, [switch] $Negate) {
\`\`\`

\[bool\] $succeeded = $ActualValue -eq 'Awesome'
	if ($Negate) { $succeeded = -not $succeeded }

	if (-not $succeeded)
	{
		if ($Negate)
		{
			$failureMessage = "{$ActualValue} is Awesome"
		}
		else
		{
			$failureMessage = "{$ActualValue} is not Awesome"
		}
	}

	return New-Object psobject -Property @{
		Succeeded      = $succeeded
		FailureMessage = $failureMessage
	}
}

Add-AssertionOperator -Name  BeAwesome `
					-Test  $function:BeAwesome `
					-Alias 'BA'

PS C:\\\> "bad" | should -BeAwesome

{bad} is not Awesome

### EXAMPLE 1
\`\`\`powershell
function BeAwesome($ActualValue, [switch] $Negate) {

\[bool\] $succeeded = $ActualValue -eq 'Awesome'
	if ($Negate) { $succeeded = -not $succeeded }

	if (-not $succeeded)
	{
		if ($Negate)
		{
			$failureMessage = "{$ActualValue} is Awesome"
		}
		else
		{
			$failureMessage = "{$ActualValue} is not Awesome"
		}
	}

	return New-Object psobject -Property @{
		Succeeded      = $succeeded
		FailureMessage = $failureMessage
	}
}

Add-AssertionOperator -Name  BeAwesome `
					-Test  $function:BeAwesome `
					-Alias 'BA'

PS C:\\\> "bad" | should -BeAwesome

{bad} is not Awesome
\`\`\`

Possible solution

Docusaurus.Powershell already used the UpdateMarkdownCodeBlock function function for adding the powershell moniker to code fences.

Perhaps something similar/smart can be done for the multi-line examples.

Additional Information (and possible solution)

More information on this PlatyPS issue here PowerShell/platyPS#180.

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://docusaurus-powershell.netlify.com

View results

Use search filter ─BROKEN─ to highlight failures

The Broken Link Checker detected one or more ⚰️ links on the website.

Please review the results and resolve as appropriate.

Pro-Tip: use search filter ─BROKEN─ to highlight failures

Exception is thrown by Test-Path here
Can repro with same string using Test-Path in unix only (pester/docs devcontainer).

$t = @"
:::note This page was generated using the comment based help in Pester $($ModuleList.Pester).
To edit the content of this page, change the corresponding help in the [pester/pester](https://github.com/pester/pester)-repository.
:::
"@

Test-Path $t

Using Test-Path -LiteralPath $t doesn't throw, but maybe better to check if string is a path first?
Haven't really identified the issue as you can solve it by any of these ways:

• Remove ::: prefix
• Remove / in the link name
• Remove square brackets in link (which are wildcard chars, so that makes sense)

The dollar character must be properly escaped in each example so that it isn't processed as a substitution

Can be tested by creating a function with the following example.

"Input" | ForEach-Object {MyFunction -Parameter $_}

Hey,

The PlatyPS MD file contains the these fields, but they are missing in the MDX

See #158

Also include a fix for the directly adjacent ` inline code block.

Website Contains Broken Links

Broken Link Checker found ⚰️ links on https://docusaurus-powershell.netlify.com/

1. View results
2. Expand node Run Broken Links Checker
3. Use log search filter ─BROKEN─ to highlight failures

To run locally:

npx broken-link-checker https://docusaurus-powershell.netlify.app/ --ordered --recursive

The Broken Link Checker detected one or more ⚰️ links on the website.

Please review the results and resolve as appropriate.

Pro-Tip: use search filter ─BROKEN─ to highlight failures

I have a few complex PS modules with 20-60 cmdlets, for the sake of clarity and discoverability we tend to group these by verb. Since discovering this module (phenomenal work btw!) I've added the ability to group cmdlets by verb in the resulting documentation as well as reflecting appropriately in the resulting sidebar with category pages. Would this be a useful addition to PR?

PS /workspaces/docs> Import-Module Alt3.Docusaurus.PowerShell                                                                                  
Import-Module: The specified module 'Alt3.Docusaurus.PowerShell' was not loaded because no valid module file was found in any module directory.

Works fine by using .psd1 path.

Root cause:
The module folder still use Powershell while the manifest use PowerShell. Renaming the folder solves it. I assume that's because the PSGallery registration is using Powershell. Possible to rename package on PSGallery?

Because PlatyPS does not add the powershell syntax highlighting language to code blocks we are currently adding the monicker ourselves during the markdown-to-mdx transformation, see https://github.com/alt3/Docusaurus.Powershell/blob/master/Source/Private/UpdateContentCodeBlocks.ps1

Ideally... a PR should be made to update PlatyPS so we can drop this step. Green light given by the repo owner, just needs to be done (see PowerShell/platyPS#475 (comment)). Additional background info at PowerShell/platyPS#294

This brings problems with cross-platform documentation using e.g. lowercase-only folders.

Should be fixed in PlatyPS as there is no way we can know what the original casing was.

A good example is this default value for OutputFolder, should be lowercase.