feat(seo): add a bunch of frontmatter titles and descriptions (#15)

RetroAchievements · Jun 3, 2024 · 9a5f33c · 9a5f33c
1 parent a9cac9b
commit 9a5f33c
Show file tree

Hide file tree

Showing 43 changed files with 244 additions and 2 deletions.
diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts
@@ -1,11 +1,43 @@
-import { defineConfig } from "vitepress";
+import { type HeadConfig, defineConfig } from "vitepress";
 // TODO search configs
 
 export const shared = defineConfig({
   // Metadata
   title: "RetroAchievements",
   head: [["script", { src: "/assets/missing-page-redirector.js" }]],
 
+  // SEO
+  /**
+   * Generate social media metadata tags at build time.
+   * Note: this does not run when using the development server,
+   * so it must be tested by doing a full build with `npm run build`.
+   */
+  transformHead({ pageData }) {
+    // Get the raw title and description from frontmatter,
+    // rather than the title which has the site suffix
+    const { title: fmTitle, description: fmDescription } = pageData.frontmatter;
+
+    const title = fmTitle ?? pageData.title;
+    const description = fmDescription ?? pageData.description;
+
+    // New meta tags to add to the <head>
+    const tags: HeadConfig[] = [];
+
+    // Add opengraph tags
+    tags.push(["meta", { property: "og:title", content: title }]);
+    tags.push(["meta", { property: "og:description", content: description }]);
+
+    // Add twitter tags
+    tags.push(["meta", { name: "twitter:site", content: "@RetroAchievements" }]);
+    tags.push(["meta", { name: "twitter:card", content: "summary_large_image" }]);
+    tags.push(["meta", { name: "twitter:title", content: title }]);
+    if (fmDescription) {
+      tags.push(["meta", { name: "twitter:description", content: description }]);
+    }
+
+    return tags;
+  },
+
   // Sitemap
   lastUpdated: true,
   sitemap: {

diff --git a/docs/developer-docs/achievement-design.md b/docs/developer-docs/achievement-design.md
@@ -1,3 +1,8 @@
+---
+title: Designing Memorable Achievements - A Comprehensive Guide
+description: Learn the conceptual principles behind creating engaging and memorable achievements, including progression-based, sidequests, optional, collectible, and challenge achievements.
+---
+
 # Achievement Design
 
 This is a guide on how to think about and design good achievements. Not the technical side, but the conceptual.

diff --git a/docs/developer-docs/achievement-development-overview.md b/docs/developer-docs/achievement-development-overview.md
@@ -1,3 +1,8 @@
+---
+title: Comprehensive Achievement Development Guide
+description: Dive deep into the craft of achievement creation with this detailed guide covering basic concepts, editor tools, protection methods, logic tips, lesser-known features, and more.
+---
+
 # Achievement Development Overview
 
 ## Intro

diff --git a/docs/developer-docs/achievement-scoring.md b/docs/developer-docs/achievement-scoring.md
@@ -1,3 +1,8 @@
+---
+title: Achievement Scoring Guidelines
+description: Learn how to score achievements effectively, considering factors like difficulty, game length, and achievement spread. Understand the point tiers and guidelines for rescoring and exceptions.
+---
+
 # Achievement Scoring
 
 ## Scoring

diff --git a/docs/developer-docs/achievement-templates.md b/docs/developer-docs/achievement-templates.md
@@ -1,3 +1,8 @@
+---
+title: Achievement Templates for Various Scenarios
+description: Explore a collection of templates for creating achievements, including examples for collecting items, finishing levels, conditional resets, and more. Learn how to adapt these templates for different games.
+---
+
 # Achievement Templates
 
 ## **WARNING: EVERY GAME IS DIFFERENT!**

diff --git a/docs/developer-docs/alt-groups.md b/docs/developer-docs/alt-groups.md
@@ -1,3 +1,8 @@
+---
+title: Utilizing Alt Groups for Achievement Requirements
+description: Learn how to use Alt Groups to create alternative requirements for unlocking achievements, including examples, facts, and advanced techniques for conditional resets.
+---
+
 # Alt Groups
 
 Achievements can have groups added to them that allow for alternative requirements to unlock an achievement. These are called _Alt Groups_,

diff --git a/docs/developer-docs/badge-and-icon-creation.md b/docs/developer-docs/badge-and-icon-creation.md
@@ -1,3 +1,8 @@
+---
+title: Badge and Icon Creation for Achievements
+description: Learn how to design and upload game icons and achievement badges, including guidelines, styling tips, and file specifications for creating visually appealing and recognizable badges.
+---
+
 # Badge and Icon Creation
 
 ## Game Icons

diff --git a/docs/developer-docs/bitcount-size.md b/docs/developer-docs/bitcount-size.md
@@ -1,3 +1,8 @@
+---
+title: Using BitCount Size in Achievement Development
+description: Learn how to use the BitCount size for counting set bits in a byte to create efficient and effective achievement conditions.
+---
+
 # `BitCount` Size
 
 `BitCount` is a shortcut for counting the number of bits set in a byte.

diff --git a/docs/developer-docs/condition-syntax.md b/docs/developer-docs/condition-syntax.md
@@ -1,3 +1,8 @@
+---
+title: Condition Syntax in Achievement Development
+description: Comprehensive guide to understanding and using condition syntax in achievement development, including memory sizes, prefixes, and logical flags.
+---
+
 # Condition Syntax
 
 ### Memory sizes

diff --git a/docs/developer-docs/console-specific-tips.md b/docs/developer-docs/console-specific-tips.md
@@ -1,3 +1,8 @@
+---
+title: Console-specific Tips for Achievement Development
+description: Essential tips and guidelines for memory inspection and achievement development across various retro consoles including NES, Game Boy, GBA, N64, DS, Neo Geo, PlayStation, and PSP.
+---
+
 # Console-specific Tips
 
 When excavating the memory of these old consoles it helps to know what the original creators of the games were working with in the first place. If you familiarize yourself with the quirks of your favorite console then set making will be easier and more accurate.

diff --git a/docs/developer-docs/delta-values.md b/docs/developer-docs/delta-values.md
@@ -1,3 +1,8 @@
+---
+title: Using Delta Values for Achievement Development
+description: Learn how to use Delta values in achievement development to detect changes between frames, such as level increases and damage detection.
+---
+
 # `Delta` Values
 
 A `Delta` value is the previous frame's value. **Note**: when you use `Delta` it is implicit that you are referring to an address and not a value.

diff --git a/docs/developer-docs/difficulty-scale-and-balance.md b/docs/developer-docs/difficulty-scale-and-balance.md
@@ -1,3 +1,8 @@
+---
+title: Difficulty Scale and Balance for Achievements
+description: Learn how to create a balanced achievement set that is fun, approachable, and challenging using a detailed difficulty scale and best practices.
+---
+
 # Difficulty Scale and Balance
 
 This doc has some suggestions about difficulty, set balance and on keeping a set fun, approachable, and challenging. What you're going to see here are not rules, just suggestions.

diff --git a/docs/developer-docs/emulator-hotkeys-for-developers.md b/docs/developer-docs/emulator-hotkeys-for-developers.md
@@ -1,3 +1,8 @@
+---
+title: Emulator Hotkeys for Achievement Developers
+description: A comprehensive guide to configuring and using emulator hotkeys for developers, including RALibRetro, BizHawk, PCSX2, RAMeka, and more.
+---
+
 # Emulator Hotkeys for Developers
 
 ### BizHawk

diff --git a/docs/developer-docs/flags/addaddress.md b/docs/developer-docs/flags/addaddress.md
@@ -1,3 +1,8 @@
+---
+title: Understanding and Using AddAddress
+description: Learn how to effectively use the AddAddress flag to modify memory addresses for conditions, understand pointer types, calculate offsets, and chain pointers for advanced achievement creation.
+---
+
 # `AddAddress`
 
 `AddAddress` modifies the memory address(es) of the following condition by the calculated value. It works similar to [`AddSource`](/developer-docs/flags/addsource), but modifies the address, not the resulting value. Additionally, it affects addresses on both sides of the condition.

diff --git a/docs/developer-docs/flags/addhits-subhits.md b/docs/developer-docs/flags/addhits-subhits.md
@@ -1,3 +1,8 @@
+---
+title: Utilizing AddHits and SubHits for Achievement Conditions
+description: Master the use of AddHits and SubHits flags to manage hit counts in achievement conditions, understand their chaining effects, and optimize achievement logic for complex scenarios.
+---
+
 # `AddHits` and `SubHits`
 
 **NOTE**: This technique is not needed for simple games, so it is not mandatory for jr-devs.

diff --git a/docs/developer-docs/flags/addsource.md b/docs/developer-docs/flags/addsource.md
@@ -1,3 +1,8 @@
+---
+title: Understanding and Utilizing AddSource for Accumulator Logic
+description: Learn how to effectively use the AddSource flag to manage accumulators in achievement conditions, including chaining, modifiers, overflow handling, and interactions with float values.
+---
+
 # `AddSource`
 
 _**Note**: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs._

diff --git a/docs/developer-docs/flags/andnext-ornext.md b/docs/developer-docs/flags/andnext-ornext.md
@@ -1,3 +1,8 @@
+---
+title: Mastering AndNext and OrNext for Complex Achievement Conditions
+description: Learn how to use the AndNext and OrNext flags to create complex conditional logic for ResetIf, PauseIf, and hit counts in achievement conditions, enabling intricate and flexible achievement requirements.
+---
+
 # `AndNext` and `OrNext`
 
 `AndNext` and `OrNext` are used to associate more than one condition to a [ResetIf](/developer-docs/flags/resetif), [PauseIf](/developer-docs/flags/pauseif), or [Hit Count](/developer-docs/hit-counts).

diff --git a/docs/developer-docs/flags/measured.md b/docs/developer-docs/flags/measured.md
@@ -1,3 +1,8 @@
+---
+title: Effectively Using Measured for Tracking Progress in Achievements
+description: Discover how to use the Measured flag to track progress in achievement conditions, manage progress bars, and optimize user experience by providing real-time feedback on achievement completion.
+---
+
 # `Measured`
 
 `Measured` marks a condition for tracking progress. It adds a progress bar to the achievement overlay to inform the user how close they are to completing an achievement. As the user expects an achievement to trigger when the progress bar is full, it is expected that any other conditions in the achievement should be true most of the time.

diff --git a/docs/developer-docs/flags/pauseif.md b/docs/developer-docs/flags/pauseif.md
@@ -1,3 +1,8 @@
+---
+title: Utilizing PauseIf to Control Achievement Hit Counts
+description: Learn how to effectively use the PauseIf flag to manage hit counts in achievements, prevent unwanted increments during specific scenarios, and understand the interaction with other conditions for optimal achievement tracking.
+---
+
 # `PauseIf`
 
 The `PauseIf` flag can be chosen in the Flag column of the Achievement Editor.

diff --git a/docs/developer-docs/flags/resetif.md b/docs/developer-docs/flags/resetif.md
@@ -1,3 +1,8 @@
+---
+title: Mastering ResetIf to Manage Achievement Hit Counts
+description: Discover how to effectively use the ResetIf flag to reset hit counts and prevent unwanted achievement triggers, ensuring precise control over achievement conditions and progression.
+---
+
 # `ResetIf`
 
 The `ResetIf` can be chosen in the Flag column of the Achievement Editor

diff --git a/docs/developer-docs/flags/resetnextif.md b/docs/developer-docs/flags/resetnextif.md
@@ -1,3 +1,8 @@
+---
+title: Effectively Using ResetNextIf to Manage Specific Hit Counts
+description: Learn how to utilize the ResetNextIf flag to selectively reset hit counts of specific conditions, ensuring precise control over achievement progression and avoiding unwanted resets.
+---
+
 # `ResetNextIf`
 
 The `ResetNextIf` Flag is a special version of the [[ResetIf Flag]] that only resets the [hit count](/developer-docs/hit-counts) of the following condition.

diff --git a/docs/developer-docs/flags/subsource.md b/docs/developer-docs/flags/subsource.md
@@ -1,3 +1,8 @@
+---
+title: Utilizing SubSource for Advanced Achievement Logic
+description: Learn how to effectively use the SubSource flag to subtract values from the accumulator, track specific increments, handle negative results, and optimize complex achievement conditions.
+---
+
 # `SubSource`
 
 _**Note**: most likely this technique is not needed for simple games. So, it's not mandatory for jr-devs._

diff --git a/docs/developer-docs/flags/trigger.md b/docs/developer-docs/flags/trigger.md
@@ -1,3 +1,8 @@
+---
+title: Leveraging the Trigger Flag for Achievement Indicators
+description: Discover how to use the Trigger flag to mark conditions that prime achievements, display challenge indicators, and enhance player experience by signaling active challenges and their statuses.
+---
+
 # `Trigger`
 
 `Trigger` marks one or more conditions in an achievement as the logic that is expected to be the final logic to become true which causes the achievement to trigger. This allows the runtime to know when an achievement is about to trigger, so a challenge indicator can be shown on the screen.

diff --git a/docs/developer-docs/game-identification.md b/docs/developer-docs/game-identification.md
@@ -1,3 +1,8 @@
+---
+title: Game Identification Methods by Console
+description: Detailed guide on the hashing methods used for game identification across various gaming consoles, including Nintendo, Sega, Sony, and more.
+---
+
 # Game Identification
 
 This page details the hashing method used for each supported system.

diff --git a/docs/developer-docs/getting-started-as-an-achievement-developer.md b/docs/developer-docs/getting-started-as-an-achievement-developer.md
@@ -1,3 +1,8 @@
+---
+title: Getting Started as an Achievement Developer
+description: Learn the basics of creating achievements for games, including finding memory addresses, creating conditions, and testing your achievements.
+---
+
 # Getting Started as an Achievement Developer
 
 **Welcome to the world of Achievement Creation!**

diff --git a/docs/developer-docs/hit-counts.md b/docs/developer-docs/hit-counts.md
@@ -1,3 +1,8 @@
+---
+title: Hit Counts
+description: Learn how to use Hit Counts in the Achievement Editor to create conditions that must be met multiple times before triggering an achievement.
+---
+
 # Hit Counts
 
 In the Achievement Editor, the field on the far right side is Hit Count.

diff --git a/docs/developer-docs/how-to-become-an-achievement-developer.md b/docs/developer-docs/how-to-become-an-achievement-developer.md
@@ -1,3 +1,8 @@
+---
+title: How to Become an Achievement Developer
+description: A step-by-step guide on how to become a RetroAchievements developer, including required knowledge, planning, and best practices.
+---
+
 # How to Become an Achievement Developer
 
 This document describes all the steps that any aspiring achievement developer must follow before getting Developer status. These requirement are also a checklist for Code Reviewers (developers who inspect the code of new developers).

diff --git a/docs/developer-docs/leaderboards.md b/docs/developer-docs/leaderboards.md
@@ -1,3 +1,8 @@
+---
+title: Leaderboards
+description: Learn how to create and manage leaderboards for RetroAchievements, including start, cancel, and submit conditions.
+---
+
 # Leaderboards
 
 [[toc]]

diff --git a/docs/developer-docs/memory-inspector.md b/docs/developer-docs/memory-inspector.md
@@ -1,3 +1,8 @@
+---
+title: Memory Inspector Overview
+description: Learn how to use the Memory Inspector tool for RetroAchievements to find and analyze game memory addresses.
+---
+
 # Memory Inspector Overview
 
 Here is an overview of the **Memory Inspector** and its features. This tool can be found on "RetroAchievements" menu on any emulator integrated with RA.

diff --git a/docs/developer-docs/minimum-required-versions-for-logic-features.md b/docs/developer-docs/minimum-required-versions-for-logic-features.md
@@ -1,3 +1,8 @@
+---
+title: Minimum Required Versions for Logic Features
+description: Detailed overview of the minimum required versions for various logic features of RetroAchievements.
+---
+
 # Minimum Required Versions for Logic Features
 
 Sometimes it's useful to know when a feature was added/changed and the implications of these changes, specially if you are working on a ticket. Compare the ticket timestamp to the toolkit releases to determine which behavior the player would have been subject to.
@@ -36,4 +41,4 @@ Sometimes it's useful to know when a feature was added/changed and the implicati
 | Float BE memory reads                                     |  1.3<br>(17 Apr 2024)  | 1.17.0<br>(3 Feb 2024)  |  11.0<br>(2 Nov 2023)  |
 | FixedN leaderboard/RP sizes                               |  1.3<br>(17 Apr 2024)  | 1.17.0<br>(3 Feb 2024)  | 11.1<br>(21 Jan 2024)  |
 | Double32 memory reads                                     |  1.3<br>(17 Apr 2024)  | 1.19.0<br>(30 May 2024) | 11.2<br>(31 Mar 2024)  |
-| Remember/recall                                           |  1.4<br>(TBD)          | TBD                     | 11.4<br>(TBD)          |
+| Remember/recall                                           |      1.4<br>(TBD)      |           TBD           |     11.4<br>(TBD)      |
diff --git a/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md b/...les/circumvent-the-problem-of-a-counter-incrementing-twice-in-the-same-frame.md
@@ -1,3 +1,8 @@
+---
+title: Solving Counter Increment Issues in the Same Frame for Achievements
+description: Learn how to handle the problem of a counter incrementing twice in the same frame using SubSource and AddHits flags, ensuring accurate achievement logic in games with simultaneous item collection.
+---
+
 # Circumvent the Problem of a Counter Incrementing Twice in the Same Frame
 
 In this example you'll see how to circumvent the problem of a counter incrementing twice in the same frame by combining [SubSource](/developer-docs/flags/subsource) and [AddHits](/developer-docs/flags/addhits-subhits).

diff --git a/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md b/...-examples/creating-a-timer-with-reset-if-hits-based-on-the-speed-of-the-game.md
@@ -1,3 +1,8 @@
+---
+title: Creating In-Game Timers with ResetIf Hits Based on Game Speed
+description: Learn how to create precise in-game timers using the ResetIf flag to account for game framerate, enabling accurate timing mechanisms for achievements in various game scenarios.
+---
+
 # Creating a Timer with `ResetIf` Hits based on the Speed of the Game
 
 In this example you will learn how to create an ingame Timer based on the framerate speed of the game.

diff --git a/...using-pause-if-to-prevent-achievement-processing-until-some-condition-is-met.md b/...using-pause-if-to-prevent-achievement-processing-until-some-condition-is-met.md
@@ -1,3 +1,8 @@
+---
+title: Using PauseIf to Control Achievement Processing
+description: Learn how to use the PauseIf flag to prevent achievement processing until specific conditions are met, ensuring accurate tracking and avoiding convoluted logic in complex scenarios.
+---
+
 # Pause Until-Using `PauseIf` to Prevent Achievement Processing Until Some Condition is Met
 
 Sometimes it will be very difficult to identify an on-going timing for when to processing hit counts or other hit-related events. Or, there are a lot of conditions for when something might look valid, but not be valid. This situation may lead to convoluted logic in order to guard against invalid hit counts. One method to mitigate this is a `Pause Until`:

diff --git a/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md b/...amples/using-add-source-and-deltas-for-collectibles-and-similar-achievements.md
@@ -1,3 +1,8 @@
+---
+title: Using AddSource and Deltas for Collectible Achievements
+description: Learn how to effectively use the AddSource flag and Deltas to create achievements for collectibles, ensuring accurate tracking and preventing premature triggers in games.
+---
+
 # Using `AddSource` and Deltas for Collectibles and Similar Achievements
 
 In this example is a simple way one can utilize the `AddSource` flag in their achievement logic.

diff --git a/...-docs/real-examples/using-delta-values-and-hit-counts-to-detect-an-increment.md b/...-docs/real-examples/using-delta-values-and-hit-counts-to-detect-an-increment.md
@@ -1,3 +1,8 @@
+---
+title: Detecting Increments with Delta Values and Hit Counts
+description: Learn how to use Delta values and hit counts to accurately detect increments for achievements, with a detailed example from Streets of Rage 2.
+---
+
 # Using Delta Values and Hit Counts to Detect an Increment
 
 Let's take [Streets of Rage 2 (Mega Drive)](http://retroachievements.org/Game/3)

diff --git a/docs/developer-docs/real-examples/using-hit-counts-as-a-timer.md b/docs/developer-docs/real-examples/using-hit-counts-as-a-timer.md
@@ -1,3 +1,8 @@
+---
+title: Using Hit Counts as a Timer for Achievements
+description: Learn how to use hit counts as a timer to create achievements that require maintaining conditions for a specific duration, illustrated with an example from Super Hang-On.
+---
+
 # Using Hit Counts as a Timer
 
 In this example, you'll see how hit counts can be used as a timer and award an achievement if a condition is true for 10 seconds.

diff --git a/docs/general/contributing-to-the-docs.md b/docs/general/contributing-to-the-docs.md
@@ -1,3 +1,8 @@
+---
+title: How to Contribute to RetroAchievements Documentation
+description: Learn how to contribute to the RetroAchievements documentation with this comprehensive guide, including how to make quick edits, detailed contributions, and best practices.
+---
+
 # Contributing to the Docs
 
 **All contributions to the docs are welcome.**

diff --git a/docs/general/emulator-support-and-issues.md b/docs/general/emulator-support-and-issues.md
@@ -1,3 +1,8 @@
+---
+title: Emulator Support
+description: Comprehensive guide to emulator support and compatibility for RetroAchievements, including console-specific issues and recommendations for various cores and emulators.
+---
+
 # Emulator Support and Issues
 
 ## Console Support

diff --git a/docs/general/tutorials/multi-disc-games.md b/docs/general/tutorials/multi-disc-games.md
@@ -1,3 +1,8 @@
+---
+title: Multi-Disc Games
+description: A comprehensive guide on handling multi-disc PlayStation games in RetroArch, including instructions for changing discs.
+---
+
 # Multi-Disc Games
 
 ## m3u files