# PSConfluencePublisher > NOTE: Due to the functionality of `xconfluencebuilder` now being part of the official [sphinxcontrib-confluencebuilder](https://github.com/sphinx-contrib/confluencebuilder) project, I am planning on refactoring to support [the official integration](https://sphinxcontrib-confluencebuilder.readthedocs.io/en/latest/configuration/#confval-confluence_manifest_data). 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)](https://bitbucket.org/tiaracodes/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](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html). ## (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](https://www.powershellgallery.com/packages/victorykit.PSConfluencePublisher). ``` PS > Install-Module victorykit.PSConfluencePublisher ``` Alternatively, you can import the module from source. In order to do that, clone the [Git repository](https://bitbucket.org/tiaracodes/psconfluencepublisher/src) , change into the directory and import it. ``` PS> git clone git@bitbucket.org:tiaracodes/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](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_preference_variables?view=powershell-7.3#debugpreference) to `Continue`, or `Inquire` in your shell's *Global* scope. ## Static Code Analysis This program requires [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules) for static code analysis. Execute `pwsh scripts/analyze.ps1` to do a static code analysis. ## Testing This program requires [Pester](https://pester.dev/) 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](https://learn.microsoft.com/en-us/nuget/install-nuget-client-tools). 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](https://www.powershellgallery.com).