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($_) } } } |