feature: Phase 22 SEO metadata component for public site
One presentational SeoHead renders the full OG/Twitter/JSON-LD head surface at prerender via typed schema.org builders. Per-medium release schema, config-sourced canonicals, 404 noindex. Zero CMS change.
This commit is contained in:
daniel-c-harvey
@@ -0,0 +1,110 @@
|
||||
using System.Text.Json;
|
||||
using System.Text.Json.Serialization;
|
||||
|
||||
namespace DeepDrftPublic.Client.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Typed schema.org JSON-LD nodes (Phase 22, OQ5 — the typed-builder option). Each record mirrors one
|
||||
/// schema.org type; <see cref="SeoJsonLd.Serialize"/> renders a node to the <c><script type="application/ld+json"></c>
|
||||
/// body. Keeping the shape in C# (not hand-written JSON in pages) is what makes the medium→type mapping
|
||||
/// live in one place (DRY, §4.3) and the output unit-testable (AC5) rather than a manual validator pass.
|
||||
///
|
||||
/// <para>
|
||||
/// All nodes share <see cref="JsonLdNode"/> so the <c>@context</c>/<c>@type</c> pair serialises first and
|
||||
/// once. Null properties are omitted (the serializer ignores nulls) so partial data never emits an empty
|
||||
/// or broken node (C6/AC4).
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public static class SeoJsonLd
|
||||
{
|
||||
private static readonly JsonSerializerOptions Options = new()
|
||||
{
|
||||
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
|
||||
// schema.org keys are PascalCase ("@type", "byArtist", "datePublished"); JsonPropertyName drives
|
||||
// each. Encoder relaxed so the JSON sits inline in HTML without over-escaping apostrophes etc.
|
||||
Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
|
||||
WriteIndented = false,
|
||||
};
|
||||
|
||||
/// <summary>Renders a node to its compact JSON-LD script body. The host component wraps it in the script tag.</summary>
|
||||
public static string Serialize<TNode>(TNode node) where TNode : JsonLdNode =>
|
||||
JsonSerializer.Serialize(node, node.GetType(), Options);
|
||||
}
|
||||
|
||||
/// <summary>Base for every schema.org node: emits <c>@context</c> and <c>@type</c> first.</summary>
|
||||
public abstract record JsonLdNode
|
||||
{
|
||||
[JsonPropertyName("@context")]
|
||||
[JsonPropertyOrder(-2)]
|
||||
public string Context => "https://schema.org";
|
||||
|
||||
[JsonPropertyName("@type")]
|
||||
[JsonPropertyOrder(-1)]
|
||||
public abstract string Type { get; }
|
||||
}
|
||||
|
||||
/// <summary>The Deep DRFT collective entity — the home/about node.</summary>
|
||||
public sealed record MusicGroupNode : JsonLdNode
|
||||
{
|
||||
public override string Type => "MusicGroup";
|
||||
|
||||
[JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
|
||||
[JsonPropertyName("url")] public string? Url { get; init; }
|
||||
[JsonPropertyName("genre")] public string? Genre { get; init; }
|
||||
[JsonPropertyName("description")] public string? Description { get; init; }
|
||||
[JsonPropertyName("logo")] public string? Logo { get; init; }
|
||||
[JsonPropertyName("sameAs")] public IReadOnlyList<string>? SameAs { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>A studio cut or a live session release. <c>AlbumProductionType</c> distinguishes them.</summary>
|
||||
public sealed record MusicAlbumNode : JsonLdNode
|
||||
{
|
||||
public override string Type => "MusicAlbum";
|
||||
|
||||
[JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
|
||||
[JsonPropertyName("byArtist")] public ArtistRef? ByArtist { get; init; }
|
||||
|
||||
/// <summary>schema.org <c>MusicAlbumProductionType</c> URI, e.g. <c>StudioAlbum</c> or <c>LiveAlbum</c>.</summary>
|
||||
[JsonPropertyName("albumProductionType")] public string? AlbumProductionType { get; init; }
|
||||
|
||||
[JsonPropertyName("datePublished")] public string? DatePublished { get; init; }
|
||||
[JsonPropertyName("genre")] public string? Genre { get; init; }
|
||||
[JsonPropertyName("image")] public string? Image { get; init; }
|
||||
[JsonPropertyName("url")] public string? Url { get; init; }
|
||||
|
||||
/// <summary>Ordered list of the album's recordings (cut track list, in TrackNumber order).</summary>
|
||||
[JsonPropertyName("track")] public IReadOnlyList<MusicRecordingNode>? Track { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>A single recording — a mix release, or one track inside an album's <c>track</c> list.</summary>
|
||||
public sealed record MusicRecordingNode : JsonLdNode
|
||||
{
|
||||
public override string Type => "MusicRecording";
|
||||
|
||||
[JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
|
||||
[JsonPropertyName("byArtist")] public ArtistRef? ByArtist { get; init; }
|
||||
|
||||
/// <summary>ISO-8601 duration (e.g. <c>PT1H2M3S</c>) from <c>DurationSeconds</c>.</summary>
|
||||
[JsonPropertyName("duration")] public string? Duration { get; init; }
|
||||
|
||||
[JsonPropertyName("genre")] public string? Genre { get; init; }
|
||||
[JsonPropertyName("image")] public string? Image { get; init; }
|
||||
[JsonPropertyName("url")] public string? Url { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>A browse/index surface listing releases (cuts/sessions/mixes/archive).</summary>
|
||||
public sealed record CollectionPageNode : JsonLdNode
|
||||
{
|
||||
public override string Type => "CollectionPage";
|
||||
|
||||
[JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
|
||||
[JsonPropertyName("description")] public string? Description { get; init; }
|
||||
[JsonPropertyName("url")] public string? Url { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>A nested <c>byArtist</c> reference — the collective as a MusicGroup, by name.</summary>
|
||||
public sealed record ArtistRef
|
||||
{
|
||||
[JsonPropertyName("@type")] public string Type => "MusicGroup";
|
||||
[JsonPropertyName("name")] public string Name { get; init; } = string.Empty;
|
||||
}
|
||||
@@ -0,0 +1,207 @@
|
||||
using DeepDrftModels.DTOs;
|
||||
using DeepDrftModels.Enums;
|
||||
|
||||
namespace DeepDrftPublic.Client.Common;
|
||||
|
||||
/// <summary>
|
||||
/// The OG <c>og:type</c> for a page. Releases map per medium (§3.4); everything else is a website.
|
||||
/// </summary>
|
||||
public enum SeoOgType
|
||||
{
|
||||
Website,
|
||||
MusicAlbum,
|
||||
MusicSong,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The typed per-page SEO input (Phase 22). A page hands <c>SeoHead</c> one model instead of ~15 loose
|
||||
/// parameters; the named factories below encode the per-page / per-medium mapping (title, description,
|
||||
/// canonical path, og:type, JSON-LD node) in exactly one place each (DRY, §4.1/§4.2). The factories are
|
||||
/// pure functions over DTOs the page already holds — unit-testable without rendering.
|
||||
///
|
||||
/// <para>
|
||||
/// <see cref="CanonicalPath"/> is site-relative; <c>SeoHead</c> absolutises it against
|
||||
/// <see cref="SeoOptions.BaseUrl"/>. Release pages pass <see cref="ReleaseRoutes.DetailHref"/> so the
|
||||
/// canonical is the dedicated route regardless of alias/query routes (AC7). A null cover means the model
|
||||
/// carries no <see cref="ImagePath"/> and <c>SeoHead</c> falls back to the default OG image (C6/AC4).
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed record SeoModel
|
||||
{
|
||||
/// <summary>Bare page title, no site suffix. <c>SeoHead</c> composes <c>"{Title} · {suffix}"</c>.</summary>
|
||||
public required string Title { get; init; }
|
||||
|
||||
/// <summary>Meta/OG description. Null falls back to <see cref="SeoOptions.DefaultDescription"/>.</summary>
|
||||
public string? Description { get; init; }
|
||||
|
||||
/// <summary>Site-relative canonical path. Null defaults to the current path in <c>SeoHead</c>.</summary>
|
||||
public string? CanonicalPath { get; init; }
|
||||
|
||||
/// <summary>Relative cover <c>ImagePath</c>. Null → the default OG image.</summary>
|
||||
public string? ImagePath { get; init; }
|
||||
|
||||
public SeoOgType OgType { get; init; } = SeoOgType.Website;
|
||||
|
||||
/// <summary>Robots directive. Null falls back to <see cref="SeoOptions.DefaultRobots"/>.</summary>
|
||||
public string? Robots { get; init; }
|
||||
|
||||
/// <summary>Pre-serialised JSON-LD script body, or null to emit no structured-data script.</summary>
|
||||
public string? JsonLd { get; init; }
|
||||
|
||||
// --- Music-vertical OG, release pages only (null elsewhere → tags omitted) ---
|
||||
public string? Artist { get; init; }
|
||||
public DateOnly? ReleaseDate { get; init; }
|
||||
public double? DurationSeconds { get; init; }
|
||||
|
||||
// ------------------------------------------------------------------ Factories
|
||||
|
||||
/// <summary>Home page: the collective entity (MusicGroup JSON-LD), site-level OG.</summary>
|
||||
public static SeoModel ForHome(SeoOptions options) => new()
|
||||
{
|
||||
Title = "Electronic Music Collective",
|
||||
Description = options.DefaultDescription,
|
||||
CanonicalPath = "/",
|
||||
OgType = SeoOgType.Website,
|
||||
JsonLd = SeoJsonLd.Serialize(MusicGroup(options)),
|
||||
};
|
||||
|
||||
/// <summary>About page: the collective again, with the bio lede as description.</summary>
|
||||
public static SeoModel ForAbout(SeoOptions options) => new()
|
||||
{
|
||||
Title = "The Collective",
|
||||
Description =
|
||||
"Two people, many hats. Deep DRFT brings the heart and soul of Midwest deep house to " +
|
||||
"Charleston — informed by the founders of the style, and promising to push it forward.",
|
||||
CanonicalPath = "/about",
|
||||
OgType = SeoOgType.Website,
|
||||
JsonLd = SeoJsonLd.Serialize(MusicGroup(options) with
|
||||
{
|
||||
Description =
|
||||
"Two people, many hats. Deep DRFT brings the heart and soul of Midwest deep house to " +
|
||||
"Charleston — informed by the founders of the style, and promising to push it forward.",
|
||||
}),
|
||||
};
|
||||
|
||||
/// <summary>A browse surface: <c>CollectionPage</c> JSON-LD, website OG.</summary>
|
||||
public static SeoModel ForBrowse(SeoOptions options, ReleaseMedium? medium, string path)
|
||||
{
|
||||
var (title, description) = BrowseCopy(medium);
|
||||
return new SeoModel
|
||||
{
|
||||
Title = title,
|
||||
Description = description,
|
||||
CanonicalPath = path,
|
||||
OgType = SeoOgType.Website,
|
||||
JsonLd = SeoJsonLd.Serialize(new CollectionPageNode
|
||||
{
|
||||
Name = title,
|
||||
Description = description,
|
||||
Url = SeoUrls.Absolute(options, path),
|
||||
}),
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>The 404 page: no canonical, <c>noindex,follow</c>, no JSON-LD.</summary>
|
||||
public static SeoModel ForNotFound(SeoOptions options) => new()
|
||||
{
|
||||
Title = "Not Found",
|
||||
Description = options.DefaultDescription,
|
||||
Robots = "noindex,follow",
|
||||
OgType = SeoOgType.Website,
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// A release detail page. The medium picks the schema (cut/session → MusicAlbum, mix → MusicRecording),
|
||||
/// the og:type, and the music-vertical OG fields; the canonical is the dedicated route. The optional
|
||||
/// <paramref name="tracks"/> seed the album's ordered <c>track</c> list (cut). <b>One call site, all tags.</b>
|
||||
/// </summary>
|
||||
public static SeoModel ForRelease(SeoOptions options, ReleaseDto release, IReadOnlyList<TrackDto>? tracks = null)
|
||||
{
|
||||
var canonicalPath = ReleaseRoutes.DetailHref(release.EntryKey, release.Medium);
|
||||
var image = SeoUrls.CoverOrDefault(options, release.ImagePath);
|
||||
var artist = new ArtistRef { Name = options.SiteName };
|
||||
var description = string.IsNullOrWhiteSpace(release.Description) ? options.DefaultDescription : release.Description;
|
||||
|
||||
// A mix is a single recording; its duration comes from the (single) track when present.
|
||||
var mixDurationSeconds = release.Medium == ReleaseMedium.Mix
|
||||
? tracks?.FirstOrDefault()?.DurationSeconds
|
||||
: null;
|
||||
|
||||
JsonLdNode node = release.Medium switch
|
||||
{
|
||||
ReleaseMedium.Mix => new MusicRecordingNode
|
||||
{
|
||||
Name = release.Title,
|
||||
ByArtist = artist,
|
||||
Duration = SeoUrls.IsoDuration(mixDurationSeconds),
|
||||
Genre = release.Genre,
|
||||
Image = image,
|
||||
Url = SeoUrls.Absolute(options, canonicalPath),
|
||||
},
|
||||
// Cut and Session are both albums; the production type distinguishes a live session.
|
||||
_ => new MusicAlbumNode
|
||||
{
|
||||
Name = release.Title,
|
||||
ByArtist = artist,
|
||||
AlbumProductionType = release.Medium == ReleaseMedium.Session
|
||||
? "https://schema.org/LiveAlbum"
|
||||
: "https://schema.org/StudioAlbum",
|
||||
DatePublished = release.ReleaseDate?.ToString("yyyy-MM-dd"),
|
||||
Genre = release.Genre,
|
||||
Image = image,
|
||||
Url = SeoUrls.Absolute(options, canonicalPath),
|
||||
Track = AlbumTracks(options, artist, tracks),
|
||||
},
|
||||
};
|
||||
|
||||
return new SeoModel
|
||||
{
|
||||
Title = release.Title,
|
||||
Description = description,
|
||||
CanonicalPath = canonicalPath,
|
||||
ImagePath = release.ImagePath,
|
||||
OgType = release.Medium == ReleaseMedium.Mix ? SeoOgType.MusicSong : SeoOgType.MusicAlbum,
|
||||
Artist = release.Artist,
|
||||
ReleaseDate = release.ReleaseDate,
|
||||
DurationSeconds = mixDurationSeconds,
|
||||
JsonLd = SeoJsonLd.Serialize(node),
|
||||
};
|
||||
}
|
||||
|
||||
// The collective entity, built once from config — the home/about JSON-LD root.
|
||||
private static MusicGroupNode MusicGroup(SeoOptions options) => new()
|
||||
{
|
||||
Name = options.SiteName,
|
||||
Url = SeoUrls.Absolute(options, "/"),
|
||||
Genre = options.Genre,
|
||||
Description = options.DefaultDescription,
|
||||
Logo = SeoUrls.Absolute(options, options.DefaultImageUrl),
|
||||
SameAs = options.SameAs.Count > 0 ? options.SameAs : null,
|
||||
};
|
||||
|
||||
// Ordered recording list for an album's `track` property. Null when there are no tracks so the
|
||||
// property is omitted rather than emitting an empty array (C6).
|
||||
private static IReadOnlyList<MusicRecordingNode>? AlbumTracks(
|
||||
SeoOptions options, ArtistRef artist, IReadOnlyList<TrackDto>? tracks)
|
||||
{
|
||||
if (tracks is null || tracks.Count == 0) return null;
|
||||
|
||||
return tracks
|
||||
.OrderBy(t => t.TrackNumber)
|
||||
.Select(t => new MusicRecordingNode
|
||||
{
|
||||
Name = t.TrackName,
|
||||
ByArtist = artist,
|
||||
Duration = SeoUrls.IsoDuration(t.DurationSeconds),
|
||||
})
|
||||
.ToList();
|
||||
}
|
||||
|
||||
private static (string Title, string Description) BrowseCopy(ReleaseMedium? medium) => medium switch
|
||||
{
|
||||
ReleaseMedium.Cut => ("Cuts", "Studio cuts from Deep DRFT — composed, layered, and finished."),
|
||||
ReleaseMedium.Session => ("Sessions", "Live sessions from Deep DRFT — performances caught in the moment, unrepeatable and unedited."),
|
||||
ReleaseMedium.Mix => ("Mixes", "DJ mixes from Deep DRFT — uninterrupted sets, one track bleeding into the next."),
|
||||
_ => ("Archive", "The full Deep DRFT catalogue — cuts, sessions, and mixes, indexed and always expanding."),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
namespace DeepDrftPublic.Client.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Site-wide SEO defaults (Phase 22). These are non-secret brand constants — a single canonical origin,
|
||||
/// the site name/suffix, the fallback share image, the social links — sourced once and injected into
|
||||
/// <c>SeoHead</c> so no page re-declares them. Registered as a singleton in
|
||||
/// <see cref="Startup.ConfigureDomainServices"/>, which runs in <b>both</b> the server prerender and the
|
||||
/// WASM passes, so both passes resolve identical values (the double-render-identity requirement, §5/AC6).
|
||||
///
|
||||
/// <para>
|
||||
/// <see cref="BaseUrl"/> is the load-bearing field: absolute canonical / <c>og:url</c> / <c>og:image</c>
|
||||
/// origins all come from here, never from a browser API — there is no <c>window.location</c> during
|
||||
/// server prerender, and the request host is unreliable behind the nginx reverse proxy (§5, OQ1).
|
||||
/// </para>
|
||||
/// </summary>
|
||||
public sealed record SeoOptions
|
||||
{
|
||||
/// <summary>Canonical production origin, no trailing slash. Absolute URLs are this + a resolved path (OQ1).</summary>
|
||||
public string BaseUrl { get; init; } = "https://deepdrft.com";
|
||||
|
||||
/// <summary>The brand name used in <c>og:site_name</c>, <c>application-name</c>, and the JSON-LD MusicGroup.</summary>
|
||||
public string SiteName { get; init; } = "Deep DRFT";
|
||||
|
||||
/// <summary>Appended to a page's bare title as <c>"{Title} · {TitleSuffix}"</c>. Resolves the prior suffix inconsistency (OQ4).</summary>
|
||||
public string TitleSuffix { get; init; } = "Deep DRFT";
|
||||
|
||||
/// <summary>Fallback meta/OG description for pages that supply none.</summary>
|
||||
public string DefaultDescription { get; init; } =
|
||||
"Deep DRFT — an electronic music collective from Charleston, South Carolina. Studio cuts, live sessions, and DJ mixes.";
|
||||
|
||||
/// <summary>
|
||||
/// Absolute or root-relative URL of the default 1200×630 share image used when a page has no cover (OQ2).
|
||||
/// A placeholder path until the real asset is dropped in; swapping it is a one-value change.
|
||||
/// </summary>
|
||||
public string DefaultImageUrl { get; init; } = "/img/og-default.png";
|
||||
|
||||
/// <summary>OG locale. Optional surface tag.</summary>
|
||||
public string Locale { get; init; } = "en_US";
|
||||
|
||||
/// <summary>The collective's primary genre, used in the MusicGroup JSON-LD node.</summary>
|
||||
public string Genre { get; init; } = "Electronic";
|
||||
|
||||
/// <summary>Default robots directive; a page may override (e.g. the 404's <c>noindex,follow</c>).</summary>
|
||||
public string DefaultRobots { get; init; } = "index,follow";
|
||||
|
||||
/// <summary>
|
||||
/// Public social profile URLs for the MusicGroup <c>sameAs</c> array (OQ3). Instagram only —
|
||||
/// no Twitter/X account exists, so no <c>twitter:site</c>/<c>twitter:creator</c> handle is emitted.
|
||||
/// </summary>
|
||||
public IReadOnlyList<string> SameAs { get; init; } = ["https://instagram.com/deepdrft.music"];
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
namespace DeepDrftPublic.Client.Common;
|
||||
|
||||
/// <summary>
|
||||
/// Absolute-URL composition for SEO tags (Phase 22). Canonical / <c>og:url</c> / <c>og:image</c> origins
|
||||
/// all come from <see cref="SeoOptions.BaseUrl"/> (config), never from a browser API — there is no
|
||||
/// <c>window.location</c> during server prerender and the request host is unreliable behind nginx
|
||||
/// (§5, OQ1). Shared by the <c>SeoModel</c> factories (which absolutise JSON-LD <c>url</c>/<c>image</c>)
|
||||
/// and <c>SeoHead</c> (which absolutises the meta/OG tags) so the rule lives in exactly one place.
|
||||
/// </summary>
|
||||
public static class SeoUrls
|
||||
{
|
||||
/// <summary>BaseUrl + a site-relative path. Both sides are trimmed so the join never doubles or drops the slash.</summary>
|
||||
public static string Absolute(SeoOptions options, string path)
|
||||
{
|
||||
var origin = options.BaseUrl.TrimEnd('/');
|
||||
if (string.IsNullOrEmpty(path)) return origin;
|
||||
return $"{origin}/{path.TrimStart('/')}";
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Absolute URL of a release/track cover from its FileDatabase <c>ImagePath</c>, via the public image
|
||||
/// route (<c>api/image/{escaped}</c>). Returns the configured default share image when no cover exists
|
||||
/// (C6/AC4 — a default guarantees <c>og:image</c> presence).
|
||||
/// </summary>
|
||||
public static string CoverOrDefault(SeoOptions options, string? imagePath)
|
||||
{
|
||||
if (string.IsNullOrWhiteSpace(imagePath))
|
||||
return Absolute(options, options.DefaultImageUrl);
|
||||
|
||||
return Absolute(options, $"api/image/{Uri.EscapeDataString(imagePath)}");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// ISO-8601 duration (e.g. <c>PT1H2M3S</c>) from a seconds value, for JSON-LD <c>duration</c> and the
|
||||
/// <c>music:duration</c> OG tag. Null / non-finite / non-positive input yields null (omit the tag).
|
||||
/// </summary>
|
||||
public static string? IsoDuration(double? seconds)
|
||||
{
|
||||
if (seconds is null || double.IsNaN(seconds.Value) || double.IsInfinity(seconds.Value) || seconds.Value <= 0)
|
||||
return null;
|
||||
|
||||
return System.Xml.XmlConvert.ToString(TimeSpan.FromSeconds(seconds.Value));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user