SEO and Analytics

SEO and Analytics

Purpose

This document records the search, social preview, structured data, and analytics architecture for the Project Forge GitHub Pages site.

Implementation Inventory

The SEO and analytics foundation consists of:

• _config.yml: GitHub Pages configuration, site identity, default layout, and non-public path exclusions.
• _data/seo.yml: canonical site settings, analytics ID, social image, theme color, and search verification token fields.
• _data/page_metadata.yml: generated title, description, canonical path, Open Graph type, and structured-data type metadata for public documentation pages.
• _includes/seo-head.html: shared metadata, favicon, social preview, structured data, and analytics head.
• _includes/analytics.html: official GA4 Google tag.
• _layouts/page.html: documentation-page layout with landmarks and one page-level H1.
• js/forge-analytics.js: no-op-safe custom GA4 event helper.
• sitemap.xml: canonical URL inventory for public pages.
• robots.txt: crawler policy and sitemap reference.
• site.webmanifest, favicon.ico, favicon-32x32.png, favicon-16x16.png, apple-touch-icon.png: browser and device icons.
• assets/project-forge-og.png: default social preview image.

Public Markdown files carry empty front matter so GitHub Pages processes them through the shared metadata layout. Their prose is unchanged.

Initial Audit Findings

The pre-implementation audit found:

• The landing page had a title and description but no canonical URL, robots directive, Open Graph metadata, Twitter Card metadata, structured data, GA4 tag, sitemap, robots file, or social preview image.
• Favicons were embedded as a data URI instead of exposed as crawlable files.
• Markdown documentation pages had no page-level SEO metadata.
• Several long-form documentation pages contained multiple Markdown H1 headings. The documentation layout now renders one page-level H1 and demotes document H1s at build time without changing source prose.
• Local Markdown links resolved; no broken local Markdown links were found.
• There were no image tags missing alt text in the HTML surfaces audited.
• GitHub Pages cannot define custom HTTP cache headers from this repository, so cache behavior is left to GitHub Pages rather than adding client-side caching.

Analytics Architecture

Project Forge uses Google Analytics 4 through the official Google tag with Measurement ID G-7PNR30M2QP.

The tag is kept in _includes/analytics.html and is included by _includes/seo-head.html, so GitHub Pages renders it into every page that uses the site metadata head. The script loads asynchronously and initializes gtag once per page.

Custom analytics helpers live in js/forge-analytics.js. The helper exposes:

• ForgeAnalytics.trackPageView(path, title)
• ForgeAnalytics.trackDocument(name)
• ForgeAnalytics.trackModule(name)
• ForgeAnalytics.trackExternalLink(url)
• ForgeAnalytics.trackDownload(filename)
• ForgeAnalytics.trackSearch(query)

Each helper checks whether gtag is available before sending. If analytics is blocked, unavailable, or still loading, the helper does nothing.

Custom GA4 events:

• view_document
• view_module
• download_document
• external_link
• search

The helper also observes link clicks for downloads, external links, and optional data-analytics-document or data-analytics-module attributes.

SEO Architecture

Shared metadata is rendered by _includes/seo-head.html.

The head includes:

• UTF-8 charset.
• Responsive viewport.
• Unique title.
• Meaningful meta description.
• Canonical URL.
• Robots directive.
• Open Graph metadata.
• Twitter Card metadata.
• Favicon and web app manifest links.
• JSON-LD structured data.
• Search engine verification meta tags when configured.

Markdown pages use _layouts/page.html. Page-specific metadata is stored in _data/page_metadata.yml so technical documents can receive accurate titles, descriptions, and canonical paths without changing the documents themselves.

Structured Data

Every page receives JSON-LD with:

• Organization
• WebSite

Technical repository and module pages may additionally receive SoftwareSourceCode when their metadata marks them as source-code surfaces.

The structured data uses canonical https://projectforge.dk URLs and the default Open Graph image.

Sitemap

sitemap.xml lists public pages using canonical URLs. Dot-directories, Python caches, and local test artifacts are excluded.

The sitemap is static and dependency-free. When public pages are added or removed, update _data/page_metadata.yml and sitemap.xml together.

robots.txt

robots.txt allows crawling and points crawlers at the sitemap:

User-agent: *
Allow: /

Sitemap: https://projectforge.dk/sitemap.xml

Metadata Strategy

Metadata describes what each page actually contains. It avoids fabricated keywords, promotional language, and claims about runtime behavior that does not exist yet.

Descriptions should identify the page as part of Project Forge’s scientific software architecture and ecosystem for long-lived computational platforms only when that accurately describes the page.

Search Engine Verification

Verification tokens are configured in _data/seo.yml:

• google_site_verification
• bing_site_verification

Add the token value there and GitHub Pages will render the corresponding meta tag across pages that use the shared SEO head.

GitHub Pages Notes

GitHub Pages supplies the HTTP cache and MIME headers for static files. This site does not add a service worker or client-side cache layer because that would increase JavaScript surface area without being necessary for the current static site.