Public/New-GhostPost.ps1

function New-GhostPost {
    <#
    .SYNOPSIS
        Creates a post on the Ghost site.

    .DESCRIPTION
        Creates a post and returns it. Only the title is required. The post is a draft unless -Status says
        otherwise; use Publish-GhostPost to publish it later, optionally by email.

        The content is Markdown, HTML or Lexical, the JSON format of the Ghost editor.

        Markdown is stored as it is, in a Markdown card, and rendered by Ghost. Ghost converts HTML to Lexical on
        a best effort basis. To keep HTML exactly as it is, wrap it in a single HTML card:
        <!--kg-card-begin: html--> ... <!--kg-card-end: html-->.

        Sync-GhostPost creates and updates posts from Markdown files that carry their own title and other fields.

    .EXAMPLE
        PS> New-GhostPost -Title 'My first post' -Html '<p>Hello world</p>'

        Creates a draft from HTML.

    .EXAMPLE
        PS> New-GhostPost -Title 'From Markdown' -Markdown (Get-Content -Path ./post.md -Raw -Encoding UTF8)

        Creates a draft from a Markdown file.

    .EXAMPLE
        PS> New-GhostPost -Title 'Release notes' -Html (Get-Content -Path ./notes.html -Raw) -Tags 'News', 'Releases'

        Creates a draft from a file and gives it two tags. Tags that do not exist yet are created.

    .EXAMPLE
        PS> New-GhostPost -Title 'Members only' -Html '<p>Hi</p>' -Visibility members -Status published

        Creates a post that is published right away and visible to members only.

    .NOTES
        The examples start with a prompt because their first line contains a greater-than sign. Get-Help takes
        everything up to the first one for the prompt, and would cut the command off.

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

    [CmdletBinding(DefaultParameterSetName = 'Lexical', SupportsShouldProcess)]
    [OutputType('Ghost.Post')]
    param(
        # Title of the post.
        [Parameter(Mandatory, Position = 0)]
        [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. Ghost derives it from the title when it is not given.
        [string] $Slug,

        # Status of the post. A scheduled post also needs -PublishedAt.
        [ValidateSet('draft', 'published', 'scheduled')]
        [string] $Status,

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

        # Mark the post as featured.
        [switch] $Featured,

        # Tags of the post: names, or objects such as @{ name = 'News'; description = '...' }. Tags that do not
        # exist are created.
        [object[]] $Tags,

        # Authors of the post: email addresses, or objects such as @{ id = '...' }. Without an author the owner
        # of the site becomes the author.
        [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. In the future for a scheduled post, in the past to backdate a published post.
        [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
    )

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

    process {
        try {
            # A copy, so that values can be added without changing what the caller passed.
            $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
            }

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

            if ($PSCmdlet.ShouldProcess($Title, $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($_)
        }
    }
}