Link Presets

Relevant source files

The following files were used as context for generating this wiki page:

• src/types/config.ts
• src/config.ts
• README.md
• src/utils/content-utils.ts
• src/components/ArchivePanel.svelte
• src/content/posts/2018-10-30/Charlotte-Markdown.md

Link Presets are a system within the Charlotte project designed to simplify the configuration of the main navigation bar. They provide a set of predefined, common navigation links (like "Home", "Archive", and "About") that can be easily added to the site's header without needing to manually specify URLs or labels. This is achieved through a TypeScript enum which acts as a shorthand.

This system allows developers to mix these presets with fully custom link objects, offering both convenience and flexibility. The presets are defined in a type-safe manner, reducing the risk of configuration errors and making the navigation bar setup more maintainable and readable.

Core Concepts

The Link Preset system is built upon a TypeScript enum and a set of related type definitions that structure the navigation bar's configuration.

The LinkPreset Enum

The foundation of the system is the LinkPreset enum, which assigns a numeric value to each standard navigation link. This allows the configuration to reference these common pages by name rather than by a hardcoded path.

// src/types/config.ts:40-44
export enum LinkPreset {
	Home = 0,
	Archive = 1,
	About = 2,
}

Sources: src/types/config.ts:40-44

The available presets are:

Preset Member	Value	Intended Page
Home	0	The main home page.
Archive	1	The post archive page.
About	2	The about/profile page.
Sources: src/types/config.ts:40-44

Navigation Bar Data Structures

The LinkPreset enum is used within the NavBarConfig type, which defines the structure for the entire navigation bar. The links property is an array that can hold either a LinkPreset enum member or a custom NavBarLink object.

The diagram below illustrates the relationship between these configuration types.

This diagram shows that NavBarConfig is composed of a list of items, where each item can be a NavBarLink object or a LinkPreset enum value.
Sources: src/types/config.ts:45-56

Implementation and Usage

Link Presets are used in the main site configuration file to populate the navigation bar. The application's frontend is then responsible for resolving these presets into actual HTML links.

Configuring the Navigation Bar

The primary configuration for the navigation bar is located in src/config.ts within the navBarConfig object. Here, developers can create the desired link structure by mixing LinkPreset members with custom link objects.

// src/config.ts:68-84
export const navBarConfig: NavBarConfig = {
	links: [
		LinkPreset.Home,
		LinkPreset.Archive,
		LinkPreset.About,
		{
			name: "书签柜",
			url: "https://tabs.chuwu.top/", 
			external: true, 
		},
		{
			name: "番茄钟",
			url: "https://pomo.chuwu.top/", 
			external: true, 
		},
	],
	opacity: 70, 
	hideButtonsOnPostPage: false, 
};

In this example, LinkPreset.Home, LinkPreset.Archive, and LinkPreset.About are used for standard internal pages, while "书签柜" (Bookmarks) and "番茄钟" (Pomodoro) are defined as custom external links.
Sources: src/config.ts:68-84, README.md:65-87

Link Resolution Flow

The following flowchart illustrates the process from configuration to the final rendered navigation link. The frontend component (e.g., a Svelte component for the navbar) interprets the navBarConfig array and generates the appropriate link for each item.

This flow demonstrates how the system differentiates between a preset and a custom link object to generate the final HTML.
Sources: src/config.ts:68-84, src/types/config.ts:45-51

While the exact rendering component is not present in the provided source files, its behavior can be inferred from the configuration structure and similar patterns in the codebase, such as the ArchivePanel.svelte component which dynamically generates post links.
Sources: src/components/ArchivePanel.svelte:70-74

Summary

The Link Presets feature in Charlotte provides a clean, type-safe, and maintainable method for managing standard navigation links. By abstracting common pages like Home, Archive, and About into an enum, it simplifies the main site configuration and reduces the potential for errors. This system, combined with the ability to add custom links, offers a robust and flexible solution for building the site's navigation structure.