Public/Set-GhostPost.ps1

function Set-GhostPost {
    <#
    .SYNOPSIS
        Updates a post on the Ghost site.

    .DESCRIPTION
        Changes the properties that are passed and leaves every other property of the post as it is. Pass an
        empty string to clear a text property. Tags and authors are replaced, not merged: pass the complete
        list.

        Ghost refuses an update when the post was changed by somebody else in the meantime. It detects that with
        the updated_at value of the post. A post from Get-GhostPost carries that value through the pipeline, so
        such an update fails when the post has changed since it was read. Without -UpdatedAt the current value
        is read first and the update always applies.

    .EXAMPLE
        Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Title 'A better title'

        Changes the title of the post.

    .EXAMPLE
        Get-GhostPost -Filter 'tag:news' | Set-GhostPost -Featured

        Marks every post with the tag news as featured.

    .EXAMPLE
        Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Html (Get-Content -Path ./post.html -Raw) -SaveRevision

        Replaces the content of the post and saves the previous content as a revision.

    .EXAMPLE
        Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -Markdown (Get-Content -Path ./post.md -Raw -Encoding UTF8)

        Replaces the content of the post with the Markdown of a file. Sync-GhostPost does this for files that
        carry their own title and other fields.

    .EXAMPLE
        Set-GhostPost -Id '5b7ada404f87d200b5b1f9c8' -CustomExcerpt ''

        Clears the custom excerpt of the post.

    .LINK
        https://docs.ghost.org/admin-api/posts/updating-a-post
    #>

    [CmdletBinding(DefaultParameterSetName = 'Lexical', SupportsShouldProcess)]
    [OutputType('Ghost.Post')]
    param(
        # Id of the post to update.
        [Parameter(Mandatory, Position = 0, ValueFromPipelineByPropertyName)]
        [ValidateNotNullOrEmpty()]
        [string] $Id,

        # The updated_at value of the post as it was read. Defaults to the current value of the post.
        [Parameter(ValueFromPipelineByPropertyName)]
        [Alias('updated_at')]
        [datetime] $UpdatedAt,

        # Title of the post.
        [ValidateNotNullOrEmpty()]
        [string] $Title,

        # Content of the post as a Lexical document: the JSON of the Ghost editor, as a string.
        [Parameter(ParameterSetName = 'Lexical')]
        [string] $Lexical,

        # Content of the post as HTML. Ghost converts it to Lexical.
        [Parameter(Mandatory, ParameterSetName = 'Html')]
        [string] $Html,

        # Content of the post as Markdown. It is stored as it is and rendered by Ghost.
        [Parameter(Mandatory, ParameterSetName = 'Markdown')]
        [AllowEmptyString()]
        [string] $Markdown,

        # Slug of the post, the last part of its address.
        [string] $Slug,

        # Status of the post. Publish-GhostPost and Unpublish-GhostPost are the usual way to change it.
        [ValidateSet('draft', 'published', 'scheduled')]
        [string] $Status,

        # Who can read the post.
        [ValidateSet('public', 'members', 'paid', 'tiers')]
        [string] $Visibility,

        # Mark the post as featured. Use -Featured:$false to remove the mark.
        [switch] $Featured,

        # Tags of the post: names, or objects such as @{ name = 'News' }. Replaces the current tags.
        [AllowEmptyCollection()]
        [object[]] $Tags,

        # Authors of the post: email addresses, or objects such as @{ id = '...' }. Replaces the current authors.
        [object[]] $Authors,

        # Address of the feature image.
        [string] $FeatureImage,

        # Alternative text of the feature image.
        [string] $FeatureImageAlt,

        # Caption of the feature image.
        [string] $FeatureImageCaption,

        # Excerpt shown in lists and previews instead of the first words of the post.
        [string] $CustomExcerpt,

        # Publication date.
        [datetime] $PublishedAt,

        # Canonical address of the post, when the original lives somewhere else.
        [string] $CanonicalUrl,

        # Title for search engines.
        [string] $MetaTitle,

        # Description for search engines.
        [string] $MetaDescription,

        # Open Graph image, used when the post is shared.
        [string] $OgImage,

        # Open Graph title.
        [string] $OgTitle,

        # Open Graph description.
        [string] $OgDescription,

        # Image for the X (Twitter) card.
        [string] $TwitterImage,

        # Title for the X (Twitter) card.
        [string] $TwitterTitle,

        # Description for the X (Twitter) card.
        [string] $TwitterDescription,

        # Code injected in the head of the post.
        [string] $CodeInjectionHead,

        # Code injected before the end of the body of the post.
        [string] $CodeInjectionFoot,

        # Name of the custom template of the theme to render the post with.
        [string] $CustomTemplate,

        # Save the content before the update as a revision of the post.
        [switch] $SaveRevision
    )

    begin {
        Test-GhostConnection
        $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name
    }

    process {
        try {
            # A copy, so that values can be added without leaking into the next object from the pipeline.
            $parameters = [hashtable]::new($PSBoundParameters, [System.StringComparer]::OrdinalIgnoreCase)
            if ($parameters.ContainsKey('Html')) {
                # Ghost ignores the html field unless it is told that HTML is the source.
                $parameters['Source'] = 'html'
            }
            if ($parameters.ContainsKey('Markdown')) {
                # Markdown travels as a Lexical document that holds one Markdown card.
                $parameters['Lexical'] = ConvertTo-GhostLexical -Markdown $Markdown
            }
            if (-not $parameters.ContainsKey('UpdatedAt')) {
                $current = @{
                    Endpoint   = $resources.URI
                    Parameters = $parameters
                    Location   = $resources.Result
                }
                $parameters['UpdatedAt'] = Get-GhostUpdatedAt @current
            }

            $uri = New-URIString -Endpoint $resources.URI -Parameters $parameters
            $uri = New-QueryString -Uri $uri -QueryKeys $resources.Query -Parameters $parameters
            $body = New-BodyString -BodyKeys $resources.Body -Parameters $parameters -Wrapper $resources.Result

            if ($PSCmdlet.ShouldProcess($Id, $resources.Description)) {
                $result = Submit-Request -Uri $uri -Method $resources.Method -Body $body -Success $resources.Success
                $result = Test-ReturnFormat -Result $result -Location $resources.Result

                Set-ObjectTypeName -InputObject $result -TypeName $resources.TypeName
            }
        }
        catch {
            $PSCmdlet.ThrowTerminatingError($_)
        }
    }
}