Public/New-GhostTag.ps1
|
function New-GhostTag { <# .SYNOPSIS Creates a tag on the Ghost site. .DESCRIPTION Creates a tag and returns it. Only the name is required; Ghost derives the slug from it. Ghost does not refuse a slug that is taken: it adds a number to it, such as news-2. Look at the slug of the tag that is returned when that matters. A name that starts with # makes an internal tag: a tag that is not shown on the site, to organize posts or to steer a theme. Ghost gives it the visibility internal and a slug that starts with hash-. A post can also create its tags itself: New-GhostPost -Tags creates the tags that do not exist yet, by name. Use this function to give a tag more than a name, or to create it before it is used. .EXAMPLE New-GhostTag -Name 'News' Creates the tag News, with the slug news. .EXAMPLE New-GhostTag -Name 'Release notes' -Slug 'releases' -Description 'What changed, version by version.' Creates a tag with a slug and a description of its own. .EXAMPLE New-GhostTag -Name '#newsletter-only' -WhatIf Shows that an internal tag would be created, without creating it. .EXAMPLE New-GhostTag -Name 'Podcast' -FeatureImage (New-GhostImage -Path ./podcast.jpg).url -AccentColor '#ff5500' Uploads an image and creates a tag that has it as its feature image, with an accent color. .LINK https://docs.ghost.org/admin-api .LINK https://docs.ghost.org/content-api/tags #> [CmdletBinding(SupportsShouldProcess)] [OutputType('Ghost.Tag')] param( # Name of the tag. A name that starts with # makes an internal tag. [Parameter(Mandatory, Position = 0)] [ValidateNotNullOrEmpty()] [string] $Name, # Slug of the tag, the last part of its address. Ghost derives it from the name when it is not given. [string] $Slug, # Description of the tag, 500 characters at most. [string] $Description, # Address of the feature image. [string] $FeatureImage, # Whether the tag is shown on the site. Ghost derives it from the name: internal for a name that starts # with #, public for any other. [ValidateSet('public', 'internal')] [string] $Visibility, # Accent color of the tag as a hexadecimal color, such as #ff5500. [ValidatePattern('^(#[0-9a-fA-F]{6})?$')] [string] $AccentColor, # Canonical address of the page of the tag, 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 page of the tag 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 page of the tag. [string] $CodeInjectionHead, # Code injected before the end of the body of the page of the tag. [string] $CodeInjectionFoot ) begin { Test-GhostConnection $resources = Get-GhostAPIData -Endpoint $MyInvocation.MyCommand.Name } process { try { $uri = New-URIString -Endpoint $resources.URI $body = New-BodyString -BodyKeys $resources.Body -Parameters $PSBoundParameters -Wrapper $resources.Result if ($PSCmdlet.ShouldProcess($Name, $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($_) } } } |