PSConfluencePublisher

🛌 NOTICE: This project is taking a quick nap until June 2025.

NOTE: Due to the functionality of xconfluencebuilder now being part of the official sphinxcontrib-confluencebuilder project, I am planning on refactoring to support the official integration. I wanted to do so anyway, since I want the test suite to both support Pester v3 and v5, which is a little tricky. The past committer is a pseudonym I've used, which I will drop for future commits.

This program is a standalone publisher component for the victorykit-xconfluencebuilder (DEFUNCT) Sphinx extension. For the history on why this program exists, check out Issue #823 of sphinx-contrib/confluencebuilder

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 [email protected]:byteb4rb1e/psconfluencepublisher.git

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

An implementation reference is provided through samples/default.

You will need the hostname (or IP address) of a Confluence instance, a Personal Access Token (PAT) and the name of a space.

The reference implementation uses manifest data generated by the sample reference implementation of xconfluencebuilder, which are 2 (ancestraly related) pages with 2 attachments (JPEG images, more importantly JPEG cat images).

To execute the sample reference implementation, run pwsh samples/default/run.ps1

$ pwsh samples/default/run.ps1 \
    -Hostname 'confluence.contoso.com' \
    -Space 'MS' \
    -PersonalAccessToken `THISISNOTAREALTOKEN`
initializing manifest...
DEBUG: Initialize-Manifest: loading manifest...
DEBUG: Initialize-Manifest: creating pages manifest index...
DEBUG: Initialize-Manifest: creating ancestral page generation cache...
DEBUG: Initialize-Manifest: sorting pages manifest...
DEBUG: Initialize-Manifest: recreating pages manifest index...
DEBUG: Initialize-Manifest: creating attachments manifest index...
initializing and testing connectivity...
Verified connectivity (confluence.contoso.com).                                                  
fetching pages metadata...
DEBUG: Get-PageMetadata: `Default Sample~`: no remote, using (partial) local                   
DEBUG: Get-PageMetadata: `Cats`: no remote, using (partial) local                              
publishing pages (2)...
Update-Page: `Default Sample~`: unknown page id. Skipping.
Update-Page: `Cats`: unknown page id. Skipping.
New-Page: `Default Sample~`: creating
New-Page: `Cats`: creating                                                                     
fetching attachments metadata...                                                               
DEBUG: Get-AttachmentMetadata: `pexels-just-a-couple-photos-3777622.jpg`: no remote, using (partial) local
DEBUG: Get-AttachmentMetadata: `pexels-sami-aksu-14356302.jpg`: no remote, using (partial) local
DEBUG: Get-AttachmentMetadata: `objects.inv`: no remote, using (partial) local                 
publishing attachments (3)...
Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: unknown attachment id. Skipping.
Update-Attachment: `pexels-sami-aksu-14356302.jpg`: unknown attachment id. Skipping.
Update-Attachment: `objects.inv`: unknown attachment id. Skipping.
New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: creating
New-Attachment: `pexels-sami-aksu-14356302.jpg`: creating                                      
New-Attachment: `objects.inv`: creating                                                        
dumping manifest to filesystem...

On the next invocation, only changed content will be updated:

$ pwsh samples/default/run.ps1 \
    -Hostname 'confluence.contoso.com' \
    -Space 'MS' \
    -PersonalAccessToken `THISISNOTAREALTOKEN`
initializing manifest...
DEBUG: Initialize-Manifest: loading manifest...
DEBUG: Initialize-Manifest: creating pages manifest index...
DEBUG: Initialize-Manifest: creating ancestral page generation cache...
DEBUG: Initialize-Manifest: sorting pages manifest...
DEBUG: Initialize-Manifest: recreating pages manifest index...
DEBUG: Initialize-Manifest: creating attachments manifest index...
initializing and testing connectivity...
Verified connectivity (confluence.contoso.com).                                                                           
fetching pages metadata...
DEBUG: Get-PageMeta: `Default Sample~`: using locally cached metadata (789703435)
DEBUG: Get-PageMeta: `Cats`: using locally cached metadata (789703436)
publishing pages (2)...
DEBUG: Update-Page: `Default Sample~`: skipping, no content changes
DEBUG: Update-Page: `Cats`: skipping, no content changes
DEBUG: New-Page: `Default Sample~`: skipping, already published (789703435)
DEBUG: New-Page: `Cats`: skipping, already published (789703436)
fetching attachments metadata...
DEBUG: Get-AttachmentMeta: `pexels-just-a-couple-photos-3777622.jpg`: using locally cached metadata (789703437)
DEBUG: Get-AttachmentMeta: `pexels-sami-aksu-14356302.jpg`: using locally cached metadata (789703438)
DEBUG: Get-AttachmentMeta: `objects.inv`: using locally cached metadata (789703439)
publishing attachments (3)...
DEBUG: Update-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, no content changes
DEBUG: Update-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, no content changes
DEBUG: Update-Attachment: `objects.inv`: skipping, no content changes
DEBUG: New-Attachment: `pexels-just-a-couple-photos-3777622.jpg`: skipping, already published (789703437)
DEBUG: New-Attachment: `pexels-sami-aksu-14356302.jpg`: skipping, already published (789703438)
DEBUG: New-Attachment: `objects.inv`: skipping, already published (789703439)
dumping manifest to filesystem...

Content can still be forcefully updated by supplying a -Force switch:

$ pwsh samples/default/run.ps1 \
    -Hostname 'confluence.contoso.com' \
    -Space 'MS' \
    -PersonalAccessToken `THISISNOTAREALTOKEN` \
    -Force

For the current moment, the top-level/root page will be applied to the root of the Confluence space. Manually move the page (as necessary) after initial publishing, recurring publishments will not require you to do so.

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 and is purely written in the PowerShell scripting language, with some built-in dependencies towards .NET Core 2 (present in all PowerShell editions).

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 disabled.

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.