Ghost CMS Integration

This guide explains how the FiNAN website integrates with Ghost CMS to manage and display blog posts. We use a headless approach where Ghost manages the content, and our Astro website fetches and displays it via the API.

Architecture

We use the @ts-ghost/content-api library to fetch content from our Ghost instance. This provides a type-safe way to query posts, tags, and authors.

• Directorysrc/

  • Directorycomponents/

    • Blog.astro # Displays recent blog posts on homepage
    • BlogRepresentation.astro # Displays country-specific posts
  • Directorylib/

    • ghost.ts # Ghost API client and fetch functions
  • Directorypages/

    • Directoryblog/

      • index.astro # Blog listing page
      • [slug].astro # Individual blog post page

Configuration

To connect to Ghost CMS, the website requires environment variables to be set.

1. Get API Keys from Ghost Admin
   Go to Settings → Integrations → Add custom integration. Name it “FiNAN Website”.

2. Add Environment Variables
   Add the following to your .env file (local) or deployment platform settings:

   GHOST_URL=https://your-ghost-blog.com
   GHOST_CONTENT_API_KEY=your_content_api_key_here

   Caution

   Never commit the .env file to version control. These keys are secrets.

3. Verify Connection
   The src/lib/ghost.ts file handles the connection. It will log a warning if keys are missing.

Fetching Data

We have a centralized API client in src/lib/ghost.ts.

Available Functions

• getBlogPosts(limit): Fetches the latest blog posts.
• getPostBySlug(slug): Fetches a single post by its URL slug.
• getAllPostSlugs(): Fetches all slugs (used for static site generation).
• getBlogPostsByTag(tag, limit): Fetches posts filtered by specific tags.

Example Usage

Here is how to fetch posts in an Astro component:

---
import { getBlogPosts } from '../lib/ghost';

const posts = await getBlogPosts(3);
---

<div class="blog-grid">
  {posts.map(post => (
    <article>
      <h2>{post.title}</h2>
      <p>{post.excerpt}</p>
      <a href={`/blog/${post.slug}`}>Read more</a>
    </article>
  ))}
</div>

Tagging Strategy (For Editors)

To ensure blog posts appear on the correct country pages (e.g., Sweden, Finland), editors must use specific tags in Ghost CMS.

Editor Guide

This section is critical for content editors.

How to Tag a Post

1. Create or Edit a Post in Ghost Admin.
2. Open the Post Settings (sidebar icon on the top right).
3. In the Tags field, type the country name.

Required Tags

Use these exact tag names to route content to specific representation pages:

Country Page	Required Tag
Finland	Finland
Sweden	Sweden
Norway	Norway
Denmark	Denmark
Iceland	Iceland
Faroe Islands	Faroe Islands

How It Works

The BlogRepresentation.astro component automatically fetches posts based on the country prop passed to it.

<!-- Example usage in src/pages/representation/sweden.astro -->
<BlogRepresentation country="sweden" />

This component converts the country name to a tag (e.g., “sweden” -> “Sweden”) and queries the Ghost API.

Error Handling

The integration is designed to be resilient.

• Missing Keys: If API keys are missing, the client returns null or empty arrays instead of crashing the build.
• API Errors: Network errors are caught and logged to the console, returning empty data to the UI.
• Missing Posts: If no posts are found for a tag, the section simply doesn’t render or shows a “No posts found” message, depending on the component.

This ensures the website remains functional even if the CMS is temporarily unavailable.