@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/site/entity/language.d.ts

@@ -1,27 +1,82 @@
 import { LanguageService, Collator } from '../type';
+/**
+ * Language - TypeScript equivalent of Go's Language entity
+ * Handles multi-language functionality
+ */
 export declare class Language {
     private langSvc;
     private currentLocation;
     private currentLanguage;
     private collator;
     constructor(langSvc: LanguageService);
+    /**
+     * Get current language index
+     * TypeScript equivalent of CurrentLanguageIndex method from Go
+     */
     currentLanguageIndex(): number;
+    /**
+     * Setup language configuration
+     * TypeScript equivalent of setup method from Go
+     */
     setup(): Promise<void>;
+    /**
+     * Get all available languages
+     * TypeScript equivalent of Languages method from Go
+     */
     languages(): Language[];
+    /**
+     * Get collator for string comparison
+     * TypeScript equivalent of Collator method from Go
+     */
     getCollator(): Collator;
+    /**
+     * Get current location (timezone)
+     * TypeScript equivalent of Location method from Go
+     */
     location(): string;
+    /**
+     * Check if site has multiple languages
+     * TypeScript equivalent of isMultipleLanguage method from Go
+     */
     isMultipleLanguage(): boolean;
+    /**
+     * Get language prefix for URLs
+     * TypeScript equivalent of LanguagePrefix method from Go
+     */
     languagePrefix(): string;
+    /**
+     * Get current language code
+     * TypeScript equivalent of Lang method from Go
+     */
     lang(): string;
     get Lang(): string;
+    /**
+     * Get current language name
+     * TypeScript equivalent of LanguageName method from Go
+     */
     languageName(): string;
     get LanguageName(): string;
+    /**
+     * Get default language name
+     * TypeScript equivalent of DefaultLanguageName method from Go
+     */
     defaultLanguageName(): string;
+    /**
+     * Get language code (alias for lang)
+     * TypeScript equivalent of LanguageCode method from Go
+     */
     languageCode(): string;
     get LanguageCode(): string;
     get LanguageDirection(): string;
+    /**
+     * Get language direction
+     * TypeScript equivalent of LanguageDirection method from Go
+     */
     languageDirection(): string;
     setCurrentLanguage(lang: string): void;
     getCurrentLanguage(): string;
+    /**
+     * Set current location/timezone
+     */
     setCurrentLocation(location: string): void;
 }

package/dist/types/internal/domain/site/entity/menu-builder.d.ts

@@ -1,19 +1,69 @@
 import { Menus } from '../valueobject/menu';
 import { ContentService } from '../type';
 import { Site } from "@internal/domain/site/entity/site";
+/**
+ * MenuBuilder - Entity responsible for building menus from frontmatter menu configurations
+ *
+ * This builder processes page frontmatter to extract menu configurations and builds
+ * hierarchical menu structures. It supports:
+ * - Multiple menu sections (nav, footer, etc.)
+ * - Menu merging across multiple files
+ * - Weight-based sorting
+ * - Smart URL generation:
+ *   - Empty URLs: Uses page permalink via site.sitePage().Permalink
+ *   - Non-empty URLs: Processed through site.getURL().relURL()
+ * - Disabled menu sections (menu: [] or menu: false)
+ */
 export declare class MenuBuilder {
     private readonly contentService;
     private readonly site;
     constructor(contentService: ContentService, site: Site);
+    /**
+     * Build menus for a specific language from frontmatter configurations
+     *
+     * Walks through all pages and extracts menu configurations from their frontmatter.
+     * Merges menu items from multiple files, handles weight-based sorting, and
+     * auto-generates URLs for empty URL fields.
+     */
     buildMenusForLanguage(langIndex: number): Promise<Menus>;
+    /**
+     * Process a single page and update menu structure based on frontmatter menu configuration
+     */
     private processPage;
+    /**
+     * Process a menu section (nav, footer, etc.) from frontmatter
+     */
     private processMenuSection;
+    /**
+     * Process menu items array and merge into menu structure
+     */
     private processMenuItems;
+    /**
+     * Process children menu items
+     */
     private processChildrenItems;
+    /**
+     * Generate page URL using site's sitePage method to get permalink
+     */
     private generatePageUrl;
+    /**
+     * Process menu item URL through site.getURL().relURL()
+     */
     private processMenuItemUrl;
+    /**
+     * Fallback URL generation from path (used when site page conversion fails)
+     */
     private fallbackUrlFromPath;
+    /**
+     * Convert MenuStructure map to Menus, grouped by menu name
+     */
     private convertToMenus;
+    /**
+     * Capitalize first letter of a string
+     */
     private capitalizeFirstLetter;
+    /**
+     * Recursively build Menu items from MenuStructure
+     */
     private buildMenuItems;
 }

package/dist/types/internal/domain/site/entity/navigation.d.ts

@@ -3,6 +3,10 @@ import { LanguageService } from '../type';
 import { Menus } from '../valueobject/menu';
 import { MenuBuilder } from './menu-builder';
 import { TaxonomyList, TaxonomiesBuilder } from "./taxonomies-builder";
+/**
+ * Navigation - TypeScript equivalent of Go's Navigation entity
+ * Handles navigation and taxonomy functionality with menu generation support
+ */
 export declare class Navigation {
     private taxonomies;
     private taxonomiesBuilder;
@@ -18,4 +22,8 @@ export declare class Navigation {
     getMenus(lang: string): Menus;
     getTaxonomies(lang: string): TaxonomyList | undefined;
 }
+/**
+ * Factory function to create new Navigation
+ * TypeScript equivalent of NewNavigation function from Go
+ */
 export declare function newNavigation(langSvc: LanguageService): Navigation;

package/dist/types/internal/domain/site/entity/page.d.ts

@@ -4,6 +4,10 @@ import { Site } from './site';
 import { Publisher } from './publisher';
 import { SitePager } from "./pager";
 import { Scratch } from "@pkg/maps/scratch";
+/**
+ * Site Page - TypeScript equivalent of Go's Page entity in domain/site/entity/page.go
+ * This wraps the content layer's Page and provides site-specific functionality
+ */
 export declare class Page implements ContentPage, PageMeta {
     private tmplSvc;
     private langSvc;
@@ -16,18 +20,60 @@ export declare class Page implements ContentPage, PageMeta {
     private _processedContent;
     private _precomputedData;
     constructor(tmplSvc: Template, langSvc: LanguageService, publisher: Publisher, contentPage: ContentPage, site: Site);
+    /**
+     * ⭐ 预计算模板需要的数据
+     * 在渲染前调用，可以并行执行
+     */
     precomputeTemplateData(): Promise<void>;
+    /**
+     * 预计算 Backlinks
+     */
     private precomputeBacklinks;
+    /**
+     * 预计算 TableOfContents
+     */
     private precomputeTableOfContents;
+    /**
+     * 预计算 Summary
+     */
     private precomputeSummary;
+    /**
+     * Process page resources
+     */
     processResources(pageSources: PageSource[]): Promise<void>;
+    /**
+     * Render the page - main entry point for page rendering
+     */
     render(): Promise<void>;
     getPageOutput(): PageOutput;
+    /**
+     * Render page content to HTML
+     * TypeScript equivalent of renderPage method from Go
+     */
     renderPage(): Promise<void>;
+    /**
+     * Render and write page content to files
+     * TypeScript equivalent of renderAndWritePage method from Go
+     */
     private renderAndWritePage;
+    /**
+     * Render page resources
+     * TypeScript equivalent of renderResources method from Go
+     */
     renderResources(): Promise<void>;
+    /**
+     * Create formatted error with context
+     * TypeScript equivalent of errorf method from Go
+     */
     private errorf;
+    /**
+     * Simple sprintf implementation
+     */
     private sprintf;
+    /**
+     * Clone the page
+     * TypeScript equivalent of clone method from Go
+     */
     clone(): Page;
     pageIdentity(): import("@internal/domain/content").PageIdentity;
     pageFile(): import("@internal/domain/content").File;
@@ -35,6 +81,10 @@ export declare class Page implements ContentPage, PageMeta {
     section(): string;
     paths(): import("../../paths").Path;
     path(): string;
+    /**
+     * Get page slug for PageGraph (Quartz-compatible format)
+     * Delegates to content page's slug() method
+     */
     slug(): string;
     file(): import("@internal/domain/content").File;
     name(): string;
@@ -49,11 +99,37 @@ export declare class Page implements ContentPage, PageMeta {
     get IsSection(): boolean;
     get IsPage(): boolean;
     get Content(): Promise<any>;
+    /**
+     * Get content with wikilinks processed
+     * This is the async version that processes wikilinks after all other content processing
+     *
+     * Usage in template:
+     *   {{ .WikilinkContent }}
+     */
     WikilinkContent(): Promise<any>;
     Summary(): Promise<string>;
     ReadingTime(): Promise<number>;
     WordCount(): Promise<number>;
+    /**
+     * Get backlinks for this page (pages that link to this page)
+     * ⭐ 优先使用预计算的缓存
+     *
+     * @returns Array of Page objects that link to this page
+     *
+     * Usage in template:
+     *   {{ range .Backlinks }}
+     *     <a href="{{ .RelPermalink }}">{{ .Title }}</a>
+     *   {{ end }}
+     *
+     * Based on Quartz Backlinks.tsx line 27:
+     * const backlinkFiles = allFiles.filter((file) => file.links?.includes(slug))
+     */
     Backlinks(): Promise<Page[]>;
+    /**
+     * Returns the outgoing links from the current page.
+     * These are populated by HtmlLinkProcessor during wikilink processing.
+     * Used by Graph component to build the knowledge graph.
+     */
     OutgoingLinks(): string[];
     get Description(): string;
     get Date(): Date;
@@ -135,7 +211,15 @@ export declare class Page implements ContentPage, PageMeta {
         Weight: number;
     };
     get Permalink(): string;
+    /**
+     * Site page conversion - convert content pages to site pages
+     * Equivalent to golang's func (p *Page) sitePages(ps contenthub.Pages) []*Page
+     */
     sitePages(ps: ContentPage[]): Page[];
+    /**
+     * Convert single content page to site page
+     * Equivalent to golang's func (p *Page) sitePage(cp contenthub.Page) (*Page, error)
+     */
     private sitePage;
     private pathJoin;
     private joinURL;
@@ -146,5 +230,9 @@ export declare class Page implements ContentPage, PageMeta {
     get Kind(): string;
     get Type(): string;
     get Parent(): Page | null;
+    /**
+     * Get site pages method - following Go's Page.Pages() pattern
+     * Equivalent to golang's func (p *Page) Pages() []*Page
+     */
     getSitePages(): Promise<Page[]>;
 }

package/dist/types/internal/domain/site/entity/pagegraph.d.ts

@@ -1,15 +1,100 @@
+/**
+ * PageGraph Entity - Simplified version following Quartz's approach
+ *
+ * Unlike complex graph structures, Quartz simply maintains:
+ * 1. An array of all slugs (for link resolution) - includes BOTH pages AND resources
+ * 2. A map of slug → outgoing links (for backlinks)
+ *
+ * Key insight from Quartz (build.ts Line 74-82):
+ * - allSlugs contains ALL files (pages + images + videos + etc.)
+ * - This enables "shortest" resolution for resources like images
+ * - Example: "pic.png" resolves to "images/pic.png" via allSlugs lookup
+ *
+ * This simplified approach:
+ * - Reduces memory footprint
+ * - Simplifies maintenance
+ * - Directly reuses Quartz's transformLink logic
+ * - Enables efficient backlinks computation
+ * - Supports wikilink image resolution (following Quartz)
+ */
 import { LinkStrategy } from '../valueobject/path';
+/**
+ * PageGraph - Site-wide knowledge for wikilink resolution and backlinks
+ *
+ * Maintains:
+ * - A list of all page AND resource slugs in the site (following Quartz)
+ * - A map of each page's outgoing links
+ *
+ * Used by:
+ * - HtmlLinkProcessor to resolve wikilinks during Pass 2
+ * - Backlinks component to find pages linking to current page
+ * - Resource resolution for images/videos (via "shortest" strategy)
+ */
 export declare class PageGraph {
     private allSlugs;
+    /** Map of page slug → outgoing links (simplified slugs) */
     private outgoingLinks;
     constructor(slugs: string[]);
+    /**
+     * Register outgoing links for a page (called during Pass 2)
+     * Based on Quartz links.ts line 162: file.data.links = [...outgoing]
+     *
+     * @param srcSlug - Source page slug
+     * @param links - Array of target slugs (simplified)
+     */
     registerOutgoingLinks(srcSlug: string, links: string[]): void;
+    /**
+     * Get pages that link to the specified page (backlinks)
+     * Based on Quartz Backlinks.tsx line 27:
+     * const backlinkFiles = allFiles.filter((file) => file.links?.includes(slug))
+     *
+     * @param targetSlug - Target page slug
+     * @returns Array of source page slugs that link to target
+     *
+     * Example:
+     * - If page "posts/a" links to "posts/b"
+     * - getBacklinks("posts/b") returns ["posts/a"]
+     */
     getBacklinks(targetSlug: string): string[];
+    /**
+     * Get all slugs in the site
+     * Used by transformLink for resolution
+     */
     getAllSlugs(): string[];
+    /**
+     * Check if a slug exists in the site
+     * Used for broken link detection
+     */
     hasSlug(slug: string): boolean;
+    /**
+     * Resolve wikilink using Quartz's transformLink logic
+     *
+     * @param srcSlug - Source page slug (e.g., "posts/my-post")
+     * @param targetLink - Target link from wikilink (e.g., "another-post" or "notes/page")
+     * @param strategy - Resolution strategy ('shortest' | 'absolute' | 'relative')
+     * @returns Resolved relative URL
+     *
+     * Examples:
+     * - resolveLink("posts/a", "b", "shortest") → "../b" (if "b" is unique)
+     * - resolveLink("posts/a", "notes/b", "absolute") → "../notes/b"
+     * - resolveLink("posts/a", "./b", "relative") → "./b"
+     */
     resolveLink(srcSlug: string, targetLink: string, strategy: LinkStrategy): string;
+    /**
+     * Get outgoing links for a page
+     * @param srcSlug - Source page slug
+     * @returns Array of simplified target slugs
+     */
     getOutgoingLinks(srcSlug: string): string[];
+    /**
+     * Get all outgoing links as a map
+     * Used for Graph visualization
+     * @returns Map of slug → outgoing links
+     */
     getAllOutgoingLinks(): Map<string, string[]>;
+    /**
+     * Get statistics about the page graph
+     */
     getStats(): {
         totalPages: number;
         slugs: string[];

package/dist/types/internal/domain/site/entity/pager.d.ts

@@ -1,5 +1,11 @@
 import { Pager } from "@internal/domain/content";
 import { Page } from "@internal/domain/site/entity/page";
+/**
+ * TypeScript equivalent of Go's SitePager struct
+ * This implements the Pager interface and wraps the content layer's Pager
+ * Equivalent to golang's type SitePager struct in domain/site/entity/paginator.go
+ * Following the same pattern as site.Page implements ContentPage
+ */
 export declare class SitePager implements Pager {
     private page;
     private pager;

package/dist/types/internal/domain/site/entity/publisher.d.ts

@@ -1,12 +1,38 @@
 import { Fs, File } from '../../fs/type';
 import { ReadableStream } from 'stream/web';
+/**
+ * Publisher publishes a result file
+ * TypeScript equivalent of Publisher struct from Go
+ */
 export declare class Publisher {
     private fs;
     constructor(fs: Fs);
+    /**
+     * PublishSource publishes content from a source buffer to files
+     * TypeScript equivalent of PublishSource method from Go
+     */
     publishSource(src: Uint8Array | string, ...filenames: string[]): Promise<void>;
+    /**
+     * PublishFiles publishes content from a readable source to files
+     * TypeScript equivalent of PublishFiles method from Go
+     */
     publishFiles(src: ReadableStream<Uint8Array>, ...filenames: string[]): Promise<void>;
+    /**
+     * Helper method to open multiple files for writing using a MultiWriter approach
+     */
     private openFilesForWriting;
+    /**
+     * Copy Uint8Array content to writer
+     */
     private copyToWriter;
+    /**
+     * Copy ReadableStream content to writer
+     */
     private copyStreamToWriter;
 }
+/**
+ * OpenFileForWriting opens or creates the given file. If the target directory
+ * does not exist, it gets created.
+ * TypeScript equivalent of OpenFileForWriting function from Go
+ */
 export declare function openFileForWriting(fs: Fs, filename: string): Promise<File>;

package/dist/types/internal/domain/site/entity/ref.d.ts

@@ -1,13 +1,40 @@
 import { ContentService, RefSite } from '../type';
+/**
+ * Ref - TypeScript equivalent of Go's Ref entity
+ * Handles page references and link generation
+ */
 export declare class Ref {
     private site;
     private contentSvc;
     private notFoundURL;
     constructor(site: RefSite, contentSvc: ContentService, notFoundURL?: string);
+    /**
+     * Generate relative reference from arguments
+     * TypeScript equivalent of RelRefFrom method from Go
+     */
     relRefFrom(argsm: Record<string, any>, source: any): Promise<string>;
+    /**
+     * Generate relative reference
+     * TypeScript equivalent of relRef method from Go
+     */
     private relRef;
+    /**
+     * Decode reference arguments
+     * TypeScript equivalent of decodeRefArgs method from Go
+     */
     private decodeRefArgs;
+    /**
+     * Generate reference link
+     * TypeScript equivalent of refLink method from Go
+     */
     private refLink;
+    /**
+     * Check if source is a Positioner
+     */
     private isPositioner;
+    /**
+     * Log not found error
+     * TypeScript equivalent of logNotFound method from Go
+     */
     private logNotFound;
 }