@mdfriday/foundry 26.4.19 → 26.5.1

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

@@ -11,6 +11,10 @@ import { Organization } from '../valueobject/organization';
 import { TaxonomyList } from "@internal/domain/site/entity/taxonomies-builder";
 import { Menus } from "@internal/domain/site/valueobject/menu";
 import { PageGraph } from './pagegraph';
+/**
+ * Site - TypeScript equivalent of Go's Site entity
+ * Main site management class
+ */
 export declare class Site {
     private configSvc;
     private contentSvc;
@@ -47,18 +51,54 @@ export declare class Site {
     Pages(): Promise<Page[]>;
     RegularPages(): Promise<Page[]>;
     constructor(configSvc: ConfigService, contentSvc: ContentService, translationSvc: TranslationService, languageSvc: LanguageService, sitemap: SitemapService, staticCopySvc: FsService, publisher: Publisher, author: Author, organization: Organization, compiler: Compiler, url: URL, ref: Ref | null, language: Language, navigation: Navigation | null, title: string);
+    /**
+     * Build site
+     * TypeScript equivalent of Build method from Go
+     */
     build(template: Template): Promise<void>;
     renderAllLanguages(): Promise<void>;
+    /**
+     * Build site with progress callbacks
+     * TypeScript equivalent of Build method from Go with progress tracking
+     */
     buildWithProgress(template: Template, onProgress?: (progress: {
         currentPage: number;
         totalPages: number;
     }) => void): Promise<void>;
+    /**
+     * Setup site before rendering
+     * TypeScript equivalent of setup method from Go
+     */
     private setup;
+    /**
+     * Render all pages
+     * TypeScript equivalent of render method from Go
+     */
     render(): Promise<void>;
+    /**
+     * Render all pages with progress tracking
+     * TypeScript equivalent of render method from Go with progress callbacks
+     */
     private renderWithProgress;
+    /**
+     * Render pages for current language
+     * TypeScript equivalent of renderPages method from Go
+     * 支持增量构建：根据环境变量判断是否只渲染 stale 页面
+     */
     private renderPages;
+    /**
+     * Render pages for current language with progress tracking
+     * TypeScript equivalent of renderPages method from Go with progress callbacks
+     */
     private renderPagesWithProgress;
+    /**
+     * Get page output (simplified implementation)
+     * TypeScript equivalent of pageOutput method from Go
+     */
     private pageOutput;
+    /**
+     * Clear site cache (simplified implementation)
+     */
     private clearSiteCache;
     translate(translationID: string): string;
     get Home(): Page | null;
@@ -67,40 +107,178 @@ export declare class Site {
     get Menus(): Menus;
     getTitle(): string;
     setTitle(title: string): void;
+    /**
+     * Get configuration service
+     */
     getConfigService(): ConfigService;
+    /**
+     * Get content service
+     */
     getContentService(): ContentService;
+    /**
+     * Get language service
+     */
     getLanguageService(): LanguageService;
+    /**
+     * Get base URL
+     * Provides the base URL service without exposing internal URL object
+     */
     baseURL(): string;
     get BaseURL(): string;
+    /**
+     * Get URL handler
+     */
     getURL(): URL;
+    /**
+     * Get reference handler
+     */
     getRef(): Ref;
+    /**
+     * Get language handler
+     */
     getLanguage(): Language;
     get Language(): Language;
     get LanguageCode(): string;
     get Languages(): Language[];
+    /**
+     * Get navigation handler
+     */
     getNavigation(): Navigation;
+    /**
+     * Get publisher
+     */
     getPublisher(): Publisher;
+    /**
+     * Get template
+     */
     getTemplate(): Template | null;
     get Author(): Author;
     get Organization(): Organization;
+    /**
+     * Get compiler info
+     */
     getCompiler(): Compiler;
+    /**
+     * Get sitemap service
+     */
     getSitemap(): SitemapService;
+    /**
+     * Check if site is multi-language
+     */
     isMultipleLanguage(): boolean;
     get IsMultilingual(): boolean;
+    /**
+     * Get current language
+     */
     getCurrentLanguage(): string;
+    /**
+     * Get language prefix for URLs
+     */
     languagePrefix(): string;
+    /**
+     * Site page factory method - convert content page to site page
+     */
     sitePage(target: ContentPage): Promise<Page>;
+    /**
+     * Convert array of content pages to array of site pages
+     * TypeScript equivalent of Go's sitePages method
+     */
     private sitePages;
+    /**
+     * Create site page from content page (synchronous version)
+     * TypeScript equivalent of Go's site page creation
+     */
     sitePageSync(contentPage: ContentPage): Page;
+    /**
+     * Pre-generate menus for all languages
+     * This ensures menus are cached before page rendering begins
+     */
     private generateNavigations;
+    /**
+     * Get page by path
+     * TypeScript equivalent of Go's GetPage method
+     * Made synchronous to match template function requirements
+     */
     GetPage(...ref: string[]): Page | null;
+    /**
+     * Copy static files to publish directory
+     * This is a core business capability of the Site entity
+     */
     copyStaticFiles(): Promise<void>;
+    /**
+     * Create site weighted page from ordinal weight page
+     * TypeScript equivalent of Go's siteWeightedPage method
+     */
     siteWeightedPage(ordinalWeightPage: any): Promise<any>;
+    /**
+     * Build PageGraph from all pages and resources
+     * Called during site setup phase (before rendering)
+     *
+     * Following Quartz's approach (build.ts Line 74-82):
+     * - Collects ALL files: pages + page resources (images, videos, etc.)
+     * - Includes resource files in allSlugs
+     * - Enables "shortest" link resolution strategy for resources
+     */
     private buildPageGraph;
+    /**
+     * Collect resource slugs from all pages
+     * Uses existing page resources (images, videos, etc. associated with pages)
+     *
+     * @param pages - All pages to collect resources from
+     * @returns Array of resource slugs (e.g., ["images/pic.png", "videos/demo.mp4"])
+     */
     private collectResourceSlugs;
+    /**
+     * Process wikilinks in HTML content (ASYNC - template engine supports it!)
+     * This method is exposed to templates for wikilink resolution
+     *
+     * @param srcSlug - Source page slug (e.g., "posts/my-post")
+     * @param html - HTML content with wikilinks
+     * @returns HTML with resolved wikilinks
+     *
+     * Usage in template:
+     *   {{ .Site.ProcessWikilinks .Page.Slug .Content }}
+     *
+     * Note: Foundry's template engine supports async methods, similar to
+     * other async methods on Site and Page instances.
+     */
     ProcessWikilinks(srcSlug: string, html: string): Promise<string>;
+    /**
+     * Get PageGraph instance (for debugging/testing)
+     */
     getPageGraph(): PageGraph | null;
+    /**
+     * Get backlinks for a specific page
+     * This method is exposed to templates for backlinks display
+     * Uses global cache for better performance
+     *
+     * @param targetSlug - Target page slug (e.g., "posts/my-post")
+     * @returns Array of source page slugs that link to target
+     *
+     * Usage in template:
+     *   {{ $backlinks := .Site.GetBacklinks .Page.Slug }}
+     *
+     * Based on Quartz Backlinks.tsx line 27:
+     * const backlinkFiles = allFiles.filter((file) => file.links?.includes(slug))
+     */
     GetBacklinks(targetSlug: string): string[];
+    /**
+     * Build backlinks cache for all pages
+     * Called after wikilink processing is complete
+     */
     buildBacklinksCache(pages: ContentPage[]): Promise<void>;
+    /**
+     * Generate contentIndex data for Graph visualization
+     * Based on Quartz contentIndex.tsx
+     *
+     * Returns a map of slug → content details including:
+     * - slug: Full page slug
+     * - title: Page title
+     * - links: Array of outgoing links (simplified slugs)
+     * - tags: Array of page tags
+     * - content: Page plain text content (truncated for performance)
+     *
+     * This data is used by the Graph component to render the knowledge graph
+     */
     GetContentIndex(): Promise<Map<string, any>>;
 }

package/dist/types/internal/domain/site/factory/navigation-factory.d.ts

@@ -6,6 +6,12 @@ export declare class NavigationFactory {
     private readonly contentService;
     private readonly site;
     constructor(langService: LanguageService, contentService: ContentService, site: Site);
+    /**
+     * Create a Navigation entity with menu building capabilities
+     */
     createNavigation(): Navigation;
 }
+/**
+ * Create navigation factory instance
+ */
 export declare function createNavigationFactory(langService: LanguageService, contentService: ContentService, site: Site): NavigationFactory;

package/dist/types/internal/domain/site/factory/site.d.ts

@@ -1,3 +1,7 @@
 import { Site } from '../entity/site';
 import { Services } from '../type';
+/**
+ * Create new Site instance with enhanced Navigation (including menu building)
+ * TypeScript equivalent of New function from Go
+ */
 export declare function newSite(services: Services): Site;

package/dist/types/internal/domain/site/service/html-link-processor.d.ts

@@ -1,20 +1,64 @@
+/**
+ * HTML Link Processor Service - Pass 2 link resolution
+ * Based on Quartz CrawlLinks transformer
+ * Source: quartz-src/quartz/plugins/transformers/links.ts
+ *
+ * This service processes HTML output from markdown rendering (Pass 1)
+ * and resolves all internal links using PageGraph knowledge.
+ */
 import { PageGraph } from '../entity/pagegraph';
 import { LinkStrategy } from '../valueobject/path';
 export interface LinkProcessorOptions {
+    /** Link resolution strategy */
     markdownLinkResolution: LinkStrategy;
+    /** Strip folders from link display */
     prettyLinks: boolean;
+    /** Open external links in new tab */
     openLinksInNewTab: boolean;
+    /** Lazy load images */
     lazyLoad: boolean;
+    /** Add icon to external links */
     externalLinkIcon: boolean;
+    /** Base URL for resolving links (e.g., "/public" or "") */
     baseURL?: string;
 }
+/**
+ * HtmlLinkProcessor - Process HTML links (Pass 2)
+ * Based on Quartz CrawlLinks plugin (lines 35-168)
+ *
+ * This processor:
+ * 1. Finds all <a> tags in HTML
+ * 2. Resolves internal links using PageGraph
+ * 3. Adds appropriate CSS classes (internal/external/broken)
+ * 4. Transforms media resource URLs (img, video, audio)
+ * 5. Optionally adds external link icons
+ * 6. Handles pretty links (show only filename)
+ */
 export declare class HtmlLinkProcessor {
     private graph;
     private options;
     constructor(graph: PageGraph, options?: Partial<LinkProcessorOptions>);
+    /**
+     * Process all links in HTML (main entry point)
+     *
+     * @param srcSlug - Source page slug (e.g., "posts/my-post")
+     * @param html - HTML content from Pass 1
+     * @returns Object with processed HTML and outgoing links
+     *
+     * Example:
+     * ```ts
+     * const processor = new HtmlLinkProcessor(pageGraph)
+     * const html = '<a data-slug="page">Page</a>'
+     * const result = await processor.processLinks("posts/a", html)
+     * // result: { html: '<a href="../page" class="internal">Page</a>', outgoingLinks: ['page'] }
+     * ```
+     */
     processLinks(srcSlug: string, html: string): Promise<{
         html: string;
         outgoingLinks: string[];
     }>;
 }
+/**
+ * Factory function to create HtmlLinkProcessor
+ */
 export declare function createHtmlLinkProcessor(graph: PageGraph, options?: Partial<LinkProcessorOptions>): HtmlLinkProcessor;

package/dist/types/internal/domain/site/type.d.ts

@@ -1,8 +1,15 @@
 import { Page as ContentPage, PageSource, WalkTaxonomyFunc } from '../content/type';
 import { ReadableStream } from 'stream/web';
 import { Fs } from '../fs/type';
+/**
+ * Services - TypeScript equivalent of Go's Services interface
+ * Main service aggregation interface
+ */
 export interface Services extends ContentService, TranslationService, ResourceService, LanguageService, FsService, URLService, ConfigService, SitemapService {
 }
+/**
+ * ConfigService - TypeScript equivalent of Go's ConfigService
+ */
 export interface ConfigService {
     configParams(): Record<string, any>;
     siteTitle(): string;
@@ -19,6 +26,9 @@ export interface ConfigService {
     getSocialLink(platformId: string): string;
     getSocialTitle(platformId: string): string;
 }
+/**
+ * ContentService - TypeScript equivalent of Go's ContentService
+ */
 export interface ContentService {
     walkPages(langIndex: number, walker: WalkFunc): Promise<void>;
     getPageSources(page: ContentPage): Promise<PageSource[]>;
@@ -30,19 +40,31 @@ export interface ContentService {
     getPageFromPathSync(langIndex: number, path: string): ContentPage | null;
     getPageRef(context: ContentPage, ref: string, home: ContentPage): Promise<ContentPage | null>;
 }
+/**
+ * TranslationService - TypeScript equivalent of Go's TranslationService
+ */
 export interface TranslationService {
     translate(lang: string, translationID: string): string;
 }
+/**
+ * ResourceService - TypeScript equivalent of Go's ResourceService
+ */
 export interface ResourceService {
     getResource(path: string): Promise<Resource | null>;
     getResourceWithOpener(path: string, opener: OpenReadSeekCloser): Promise<Resource>;
 }
+/**
+ * LanguageService - TypeScript equivalent of Go's LanguageService
+ */
 export interface LanguageService {
     defaultLanguage(): string;
     languageKeys(): string[];
     getLanguageIndex(lang: string): number;
     getLanguageName(lang: string): string;
 }
+/**
+ * SitemapService - TypeScript equivalent of Go's SitemapService
+ */
 export interface SitemapService {
     changeFreq(): string;
     priority(): number;
@@ -50,72 +72,126 @@ export interface SitemapService {
         urls: any[];
     }>;
 }
+/**
+ * Walk function types
+ */
 export type WalkFunc = (page: ContentPage) => Promise<void>;
+/**
+ * Menu - TypeScript equivalent of Go's Menu interface
+ */
 export interface Menu {
     name(): string;
     url(): string;
     weight(): number;
 }
+/**
+ * Resource interface
+ */
 export interface Resource {
     name(): string;
     readSeekCloser(): Promise<ReadableStream<Uint8Array>>;
     targetPath(): string;
 }
+/**
+ * OpenReadSeekCloser - TypeScript equivalent of Go's io.OpenReadSeekCloser
+ */
 export type OpenReadSeekCloser = () => Promise<ReadableStream<Uint8Array>>;
+/**
+ * FsService - TypeScript equivalent of Go's FsService
+ */
 export interface FsService {
     publishFs(): Fs;
     staticFs(): Fs;
     copyStaticFiles(from: Fs, to: Fs): Promise<void>;
     workingDir(): string;
 }
+/**
+ * URLService - TypeScript equivalent of Go's URLService
+ */
 export interface URLService {
     baseUrl(): string;
 }
+/**
+ * Author interface
+ */
 export interface Author {
     name(): string;
     email(): string;
 }
+/**
+ * Organization interface
+ */
 export interface Organization {
     name(): string;
     description(): string;
     website(): string;
 }
+/**
+ * Compiler interface
+ */
 export interface Compiler {
     version(): string;
     environment(): string;
 }
+/**
+ * Site interface - minimal implementation for dependencies
+ */
 export interface Site {
     currentLanguage: string;
     baseURL(): string;
 }
+/**
+ * RefArgs interface - TypeScript equivalent of valueobject.RefArgs
+ */
 export interface RefArgs {
     path: string;
     outputFormat: string;
 }
+/**
+ * RefSite interface for Ref dependencies
+ */
 export interface RefSite {
     home: {
         page: ContentPage;
     };
     sitePage(target: ContentPage): Promise<SitePage>;
 }
+/**
+ * SitePage interface with permalink methods
+ */
 export interface SitePage {
     relPermalink(): string;
     permalink(): string;
     path?(): string;
 }
+/**
+ * PageWrapper interface
+ */
 export interface PageWrapper {
     unwrapPage(): ContentPage;
 }
+/**
+ * Position interface for error reporting
+ */
 export interface Position {
     isValid(): boolean;
     toString(): string;
 }
+/**
+ * Positioner interface
+ */
 export interface Positioner {
     position(): Position;
 }
+/**
+ * Menus interface - TypeScript equivalent of valueobject.Menus
+ */
 export interface Menus {
     [key: string]: any;
 }
+/**
+ * BaseURL interface
+ */
 export interface BaseURL {
     protocol(): string;
     host(): string;
@@ -126,6 +202,9 @@ export interface BaseURL {
     getRoot(path: string): string;
     basePathNoTrailingSlash: string;
 }
+/**
+ * URLSite interface
+ */
 export interface URLSite {
     baseURL(): BaseURL;
     absURL(input: string): string;
@@ -134,19 +213,31 @@ export interface URLSite {
     languagePrefix(): string;
     isMultipleLanguage(): boolean;
 }
+/**
+ * Language - TypeScript equivalent of Go's Language interface
+ */
 export interface Language {
     location(): string;
     collator(): Collator;
 }
+/**
+ * Collator interface for string comparison
+ */
 export interface Collator {
     compare(a: string, b: string): number;
 }
+/**
+ * URL - TypeScript equivalent of Go's URL interface
+ */
 export interface URL {
     base: string;
     absURL(input: string): string;
     relURL(input: string): string;
     urlize(uri: string): string;
 }
+/**
+ * Template - TypeScript equivalent of Go's Template interface
+ */
 export interface Template {
     lookupLayout(names: string[]): Promise<{
         preparer: TemplatePreparer;
@@ -154,12 +245,21 @@ export interface Template {
     }>;
     executeWithContext(preparer: TemplatePreparer, data: any): Promise<string>;
 }
+/**
+ * TemplatePreparer interface
+ */
 export interface TemplatePreparer {
     name(): string;
     execute(data: any): Promise<string>;
 }
+/**
+ * ContentSpec - TypeScript equivalent of Go's ContentSpec
+ */
 export interface ContentSpec {
     preparePages(): Promise<void>;
     renderPages(handler: RenderHandler): Promise<void>;
 }
+/**
+ * RenderHandler function type
+ */
 export type RenderHandler = (kind: string, sections: string[], dir: string, name: string, content: string) => Promise<void>;

package/dist/types/internal/domain/site/valueobject/author.d.ts

@@ -1,4 +1,7 @@
 import { Author as ContentAuthor } from '@internal/domain/content';
+/**
+ * Social link item with ID and Link properties
+ */
 export interface SocialLink {
     ID: string;
     Link: string;
@@ -8,13 +11,26 @@ export declare class Author {
     private readonly _email;
     private _homeAuthor;
     constructor(name: string, email: string);
+    /**
+     * Get author name
+     */
     name(): string;
+    /**
+     * Get author email
+     */
     email(): string;
     author(author: ContentAuthor | undefined): Author;
     get Name(): string;
     get Description(): string;
     get Avatar(): string;
     get Twitter(): string;
+    /**
+     * Get all social links as array of objects with ID and Link properties
+     */
     get Socials(): SocialLink[];
 }
+/**
+ * Factory function to create new Author
+ * TypeScript equivalent of NewAuthor function from Go
+ */
 export declare function newAuthor(name: string, email: string): Author;

package/dist/types/internal/domain/site/valueobject/baseurl.d.ts

@@ -7,18 +7,57 @@ export declare class BaseURL {
     readonly basePathNoTrailingSlash: string;
     readonly isRelative: boolean;
     private constructor();
+    /**
+     * Creates a new BaseURL instance from a string.
+     * Supports various formats:
+     * - Absolute URLs: https://example.com/, https://example.com/public/
+     * - Relative paths: /public/, /
+     * - Protocol-relative URLs: //example.com/
+     */
     static fromString(baseUrl: string): BaseURL;
+    /**
+     * Returns the appropriate root URL based on the path.
+     */
     getRoot(path: string): string;
     toString(): string;
     path(): string;
     port(): number;
+    /**
+     * Returns the URL to the host root without any path elements.
+     */
     hostURL(): string;
+    /**
+     * Returns the protocol (scheme) of the URL.
+     */
     protocol(): string;
+    /**
+     * Returns the host (hostname + port) of the URL.
+     */
     host(): string;
+    /**
+     * Returns the hostname of the URL.
+     */
     hostname(): string;
+    /**
+     * Returns a copy of the internal URL.
+     * The copy can be safely used and modified.
+     */
     getURL(): URL;
+    /**
+     * Returns the BaseURL prefixed with the given protocol.
+     * The Protocol is normally of the form "scheme://", i.e. "webcal://".
+     */
     withProtocol(protocol: string): BaseURL;
+    /**
+     * Returns a new BaseURL with the specified port.
+     */
     withPort(port: number): BaseURL;
+    /**
+     * Checks if this BaseURL is relative (path-only).
+     */
     isRelativeURL(): boolean;
+    /**
+     * Checks if this BaseURL is absolute (has protocol and host).
+     */
     isAbsoluteURL(): boolean;
 }