PSConfluencePublisher

This program is a standalone publisher component for the victorykit-xconfluencebuilder Sphinx extension.

It consumes, a JSON-formatted manifest of a Sphinx build dump generated by the victorykit-xconfluencebuilder and unidirectionally synchronizes pages, page ancestry, and attachments.

Publishing is supported via the Confluence Server REST API through Personal Access Token (PAT) authorization.

(Interchange) Manifest

The manifest consists of a Pages manifest and an Attachments manifest, which store metadata on pages and attachments. Even though the Pages manifests (represented as array object) is expected to have the appropriate order for publishing, where the oldest ancestral generation of pages is published before the youngest, this isn't trusted and the pages manifest is ordered in-place, through a Hoare partitioned Quick-Sort via the Optimize-PagesManifest function.

The manifest is treated as read/write and used for storing additional metadata to reduce the amount of remote data retrieval. This includes hashing of page and attachments content in addition to tracking publishing versions and remote ids. Through a JSONSchema, it is made sure that the manifest stays consistent for interchange with the original manifest producer system (victorykit-xconfluencebuilder).

Usage

You may install this PowerShell module via PowerShellGallery.

PS > Install-Module victorykit.PSConfluencePublisher

Alternatively, you can import the module from source. In order to do that, clone the Git repository , change into the directory and import it.

PS> git clone git@bitbucket.org:victorykit/psconfluencepublisher.git

PS> # universal import statement compatible with PowerShell Core & Desktop
PS> Import-Module "src/PSConfluencePublisher.psd1"

Next, register your personal access token for your Confluence server instance. The token is stored as a SecureString type within the scope of the responsible ested module (PersonalAccessToken). It is expected to have one Personal Access Token per Confluence instance, per PowerShell session.

Register-PersonalAccessToken `
    -Host 'confluence.contoso.com' `
    -Token '123456789123456789'

Optionally, you may test the connectivity to your Confluence instance. The test will try to retrieve your user profile, in order to determine whether the PAT authenticates, since an invalid PAT may results in anonymous authentication, that does not return a fault HTTP status code for some REST API functions.

Test-Connection confluence.contoso.com

Now you may publish by supplying the URL of the root Confluence page you want to publish to, in addition to the location of the local dump manifest. Make sure to use the full URL, with the same hostname as the one you used to register your personal access token.

Publish-Dump `
    -Url 'https://confluence.contoso.com/display/TIARA/Testitest' `
    -DumpIndex build/docs/confluence.out/data.json

The manifest MUST be writable, where it is then used to cache the publishing status of each page and attachment.

You may publish a single page, which however requires it's direct ancestral page to exist.

Publish-Page

Compatibility

This program is compatible with the following Microsoft PowerShell runtimes:

Microsoft PowerShell Desktop >=5
Microsoft PowerShell Core >=7

Runtime Dependencies

This program has no runtime dependencies.

On PowerShell Desktop, however, it is necessary to obtain the Microsoft.PowerShell.Utility module for JSON schema verification of the manifest. Whether that's possible for PowerShell Desktop; We do not know. Should the aforementioned module not be present, JSON validation is skipped.

Debugging

To display debug messages, set $DebugPreference to Continue, or Inquire in your shell's Global scope.

Static Code Analysis

This program requires PSScriptAnalyzer for static code analysis.

Execute pwsh scripts/analyze.ps1 to do a static code analysis.

Testing

This program requires Pester to execute it's test suite.

The test suite aims to be executable under most circumstances. We've been dropping usage of Pester v5 functionalities so that it works with Pester down to version 3, since Pester v3 is available in PowerShell (5) Desktop by default. Due to the security mechanisms implemented in PowerShell Desktop, installing the Pester v5 module may not be feasible for some.

Execute pwsh scripts/test.ps1 to run the entire test suite.

Packaging & Publishing

This program does not adhere to Microsoft's Best-Practices of publishing PowerShell modules, in the sense of that it does not use the PowerShellGet module to do so and uses the plain nuget CLI instead.

This program requires nuget CLI. Be aware that the dotnet nuget CLI may not be sufficient on some platforms.

Execute pwsh scripts/pack.ps1 to create the nuget package.

Execute pwsh scripts/publish.ps1 to publish the nuget package to PowerShellGallery.

5.5 KiB Executable file Raw Blame History