@mdfriday/foundry 26.4.19 → 26.5.1

package/dist/types/internal/domain/identity/value-object/token.d.ts

@@ -1,19 +1,54 @@
+/**
+ * Token Value Object
+ *
+ * 不可变的认证令牌值对象
+ */
 export declare class Token {
     private readonly value;
     private readonly expiresAt;
     private constructor();
+    /**
+     * 创建 Token 实例
+     */
     static create(value: string, expiresAt?: number): Token;
+    /**
+     * 从 JSON 数据创建 Token
+     */
     static fromJSON(data: {
         token: string;
         expiresAt?: number;
     }): Token;
+    /**
+     * 获取 token 字符串
+     */
     getValue(): string;
+    /**
+     * 获取过期时间（毫秒时间戳）
+     */
     getExpiresAt(): number | undefined;
+    /**
+     * 检查 token 是否已过期
+     */
     isExpired(): boolean;
+    /**
+     * 检查 token 是否有效（未过期）
+     */
     isValid(): boolean;
+    /**
+     * 获取剩余有效时间（毫秒）
+     */
     getRemainingTime(): number | null;
+    /**
+     * 比较两个 Token 是否相等
+     */
     equals(other: Token): boolean;
+    /**
+     * 转换为字符串（返回 token 值）
+     */
     toString(): string;
+    /**
+     * 序列化为 JSON
+     */
     toJSON(): {
         token: string;
         expiresAt?: number;

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

@@ -1,4 +1,8 @@
 import { ContentResult, DocumentContext, Highlighter, Markdown, MarkdownRenderer, ParseAndRenderOptions, ParsedContentResult, RenderableDocument, RenderContext, Result } from '../type';
+/**
+ * MarkdownImpl implements the main Markdown interface
+ * This is the TypeScript equivalent of the Go entity.Markdown
+ */
 export declare class MarkdownImpl implements Markdown {
     private renderer;
     private highlighter;
@@ -9,16 +13,53 @@ export declare class MarkdownImpl implements Markdown {
     renderCodeblock(cctx: any, w: import('../type').FlexiWriter, ctx: import('../type').CodeblockContext): Promise<void>;
     isDefaultCodeBlockRenderer(): boolean;
     prepareRender(source: Uint8Array): Promise<RenderableDocument>;
+    /**
+     * Parse and render content in one step - simplified interface for external use
+     * This method hides implementation details and provides a clean interface
+     */
     parseAndRenderContent(source: Uint8Array, options?: ParseAndRenderOptions): Promise<ContentResult>;
+    /**
+     * Check if the renderer supports tag collection (MarkdownItRenderer)
+     */
     private hasCollectedTagsSupport;
+    /**
+     * Get collected tags from renderer (if supported)
+     */
     private getCollectedTags;
+    /**
+     * Parse markdown source with front matter and shortcodes
+     */
     parseContent(source: Uint8Array): Promise<ParsedContentResult>;
+    /**
+     * Parse front matter from item
+     */
     private parseFrontMatter;
+    /**
+     * Simple YAML parser (basic implementation)
+     */
     private parseYAML;
+    /**
+     * Simple TOML parser using smol-toml library
+     */
     private parseTOML;
+    /**
+     * Simple JSON parser
+     */
     private parseJSON;
+    /**
+     * Simple Org mode parser (basic implementation)
+     */
     private parseOrg;
+    /**
+     * Parse value (string, number, boolean, array)
+     */
     private parseValue;
+    /**
+     * Parse markdown source into tokens and create parsing result
+     */
     private parse;
+    /**
+     * Render the parsed result to bytes
+     */
     private renderToBytes;
 }

package/dist/types/internal/domain/markdown/factory/it/config.d.ts

@@ -1,9 +1,15 @@
+/**
+ * Auto heading ID types
+ */
 export declare const AutoHeadingIDType: {
     readonly GitHub: "github";
     readonly GitHubAscii: "github-ascii";
     readonly Blackfriday: "blackfriday";
 };
 export type AutoHeadingIDType = typeof AutoHeadingIDType[keyof typeof AutoHeadingIDType];
+/**
+ * Typographer configuration
+ */
 export interface TypographerConfig {
     disable: boolean;
     leftSingleQuote: string;
@@ -17,20 +23,32 @@ export interface TypographerConfig {
     rightAngleQuote: string;
     apostrophe: string;
 }
+/**
+ * CJK configuration
+ */
 export interface CJKConfig {
     enable: boolean;
     eastAsianLineBreaks: boolean;
     eastAsianLineBreaksStyle: string;
     escapedSpace: boolean;
 }
+/**
+ * Delimiters configuration
+ */
 export interface DelimitersConfig {
     inline: string[][];
     block: string[][];
 }
+/**
+ * Passthrough configuration
+ */
 export interface PassthroughConfig {
     enable: boolean;
     delimiters: DelimitersConfig;
 }
+/**
+ * Highlight configuration
+ */
 export interface HighlightConfig {
     style: string;
     lineNos: boolean;
@@ -43,31 +61,55 @@ export interface HighlightConfig {
     guessSyntax: boolean;
     tabWidth: number;
 }
+/**
+ * Parser attribute configuration
+ */
 export interface ParserAttributeConfig {
     title: boolean;
     block: boolean;
 }
+/**
+ * Parser configuration
+ */
 export interface ParserConfig {
     autoHeadingID: boolean;
     autoHeadingIDType: AutoHeadingIDType;
     wrapStandAloneImageWithinParagraph: boolean;
     attribute: ParserAttributeConfig;
 }
+/**
+ * Renderer configuration
+ */
 export interface RendererConfig {
     unsafe: boolean;
 }
+/**
+ * Wikilink configuration
+ */
 export interface WikilinkConfig {
     enable: boolean;
+    /** Disable broken wikilink rendering */
     disableBrokenWikilinks?: boolean;
+    /** Link resolution strategy for Pass 2 */
     markdownLinkResolution?: 'absolute' | 'relative' | 'shortest';
+    /** Pretty links (show only filename) */
     prettyLinks?: boolean;
 }
+/**
+ * LaTeX configuration
+ */
 export interface LatexConfig {
     enable: boolean;
 }
+/**
+ * Mermaid diagram configuration
+ */
 export interface MermaidConfig {
     enable: boolean;
 }
+/**
+ * Extensions configuration
+ */
 export interface ExtensionsConfig {
     typographer: TypographerConfig;
     footnote: boolean;
@@ -86,16 +128,28 @@ export interface ExtensionsConfig {
     latex?: LatexConfig;
     mermaid?: MermaidConfig;
 }
+/**
+ * Image render hook configuration
+ */
 export interface ImageRenderHookConfig {
     enableDefault: boolean;
 }
+/**
+ * Link render hook configuration
+ */
 export interface LinkRenderHookConfig {
     enableDefault: boolean;
 }
+/**
+ * Render hooks configuration
+ */
 export interface RenderHooksConfig {
     image: ImageRenderHookConfig;
     link: LinkRenderHookConfig;
 }
+/**
+ * Main Markdown configuration
+ */
 export interface DomainMarkdownConfig {
     renderer: RendererConfig;
     parser: ParserConfig;
@@ -103,5 +157,11 @@ export interface DomainMarkdownConfig {
     duplicateResourceFiles: boolean;
     renderHooks: RenderHooksConfig;
 }
+/**
+ * Default highlight configuration
+ */
 export declare const DefaultHighlightConfig: HighlightConfig;
+/**
+ * Default markdown configuration
+ */
 export declare const DefaultMarkdownConfig: DomainMarkdownConfig;

package/dist/types/internal/domain/markdown/factory/it/index.d.ts

@@ -1,23 +1,43 @@
 import MarkdownIt from 'markdown-it';
-import Token from 'markdown-it/lib/token.mjs';
+import type Token from 'markdown-it/lib/token.mjs';
 import { DomainMarkdownConfig } from './config';
 import { MarkdownRenderer, ParsingResult } from "@internal/domain/markdown";
+/**
+ * MarkdownIt-based renderer implementation
+ */
 export declare class MarkdownItRenderer implements MarkdownRenderer {
     private md;
     private config;
     private idGenerator;
     private collectedTags;
     constructor(config: DomainMarkdownConfig, externalMd?: MarkdownIt);
+    /**
+     * Set up custom renderer rules (heading auto ID, etc.)
+     * Called once during initialization, not on every render
+     */
     private setupRendererRules;
     render(source: string): Promise<string>;
+    /**
+     * Get collected tags from last render
+     * These tags should be injected into frontmatter.tags
+     */
     getCollectedTags(): string[];
     parse(source: string): Promise<ParsingResult>;
     _parse(source: string): Promise<Token[]>;
+    /**
+     * Get the underlying MarkdownIt instance
+     */
     getMarkdownIt(): MarkdownIt;
+    /**
+     * Add a custom plugin
+     */
     addPlugin(plugin: any, options?: any): void;
     private createMarkdownItInstance;
     private configureBasicPlugins;
 }
+/**
+ * Factory function to create MarkdownIt renderer with default configuration
+ */
 export declare function createMarkdownItRenderer(config?: Partial<DomainMarkdownConfig>, externalMd?: MarkdownIt): MarkdownItRenderer;
 export { DomainMarkdownConfig, DefaultMarkdownConfig } from './config';
 export { ParserResult } from './parserresult';

package/dist/types/internal/domain/markdown/factory/it/parserresult.d.ts

@@ -1,6 +1,9 @@
 import Token from 'markdown-it/lib/token.mjs';
 import { ParsingResult, Header, TocFragments } from '../../index';
 import { AutoIDGenerator } from '@internal/domain/markdown/vo/tableofcontents';
+/**
+ * ParserResult implements ParsingResult
+ */
 export declare class ParserResult implements ParsingResult {
     private _headers;
     private _toc;

package/dist/types/internal/domain/markdown/factory/it/plugins/callout-plugin.d.ts

@@ -1,6 +1,46 @@
+/**
+ * markdown-it plugin for Obsidian-style callouts
+ *
+ * Ported from Quartz v4: quartz/plugins/transformers/ofm.ts (callout handling)
+ *
+ * This plugin follows markdown-it best practices:
+ * 1. Block parsing rule to recognize blockquote-based callout syntax
+ * 2. Token-based representation
+ * 3. Custom renderer for callout HTML output
+ *
+ * Supports:
+ * - All Obsidian callout types: note, abstract, info, todo, tip, success, etc.
+ * - Custom titles: > [!note] Custom Title
+ * - Foldable callouts: > [!note]+ (expanded) or > [!note]- (collapsed)
+ * - Nested content with proper formatting
+ *
+ * Syntax:
+ * ```markdown
+ * > [!note] Optional Title
+ * > Content line 1
+ * > Content line 2
+ * ```
+ */
 import MarkdownIt from 'markdown-it';
+/**
+ * Plugin options
+ */
 export interface CalloutPluginOptions {
+    /** Enable/disable callout parsing */
     enable?: boolean;
 }
+/**
+ * markdown-it plugin interface
+ *
+ * Usage:
+ *   const md = new MarkdownIt();
+ *   md.use(calloutPlugin, { enable: true });
+ *
+ * @param md - MarkdownIt instance
+ * @param options - Plugin options
+ */
 export declare function calloutPlugin(md: MarkdownIt, options?: CalloutPluginOptions): void;
+/**
+ * Export as default for convenience
+ */
 export default calloutPlugin;

package/dist/types/internal/domain/markdown/factory/it/plugins/latex-plugin.d.ts

@@ -1,6 +1,29 @@
+/**
+ * LaTeX markdown-it plugin for Quartz-style math expressions
+ * Reference: quartz-src/quartz/plugins/transformers/latex.ts
+ *
+ * This plugin identifies $...$ (inline) and $$...$$ (block) math expressions
+ * and generates HTML with data attributes for client-side KaTeX rendering.
+ *
+ * Unlike remark-math + rehype-katex used in Quartz, we use markdown-it's
+ * inline/block rule system to achieve the same result.
+ */
 import MarkdownIt from 'markdown-it';
 export interface LatexPluginOptions {
     enable?: boolean;
 }
+/**
+ * markdown-it plugin interface
+ *
+ * Usage:
+ *   const md = new MarkdownIt();
+ *   md.use(latexPlugin, { enable: true });
+ *
+ * @param md - MarkdownIt instance
+ * @param options - Plugin options
+ */
 export declare function latexPlugin(md: MarkdownIt, options?: LatexPluginOptions): void;
+/**
+ * Export as default for convenience
+ */
 export default latexPlugin;

package/dist/types/internal/domain/markdown/factory/it/plugins/mermaid-plugin.d.ts

@@ -1,6 +1,30 @@
+/**
+ * Mermaid markdown-it plugin for Quartz-style diagram rendering
+ * Reference: quartz-src/quartz/components/scripts/mermaid.inline.ts
+ *
+ * This plugin identifies ```mermaid code blocks and adds the 'mermaid' class
+ * for client-side rendering.
+ *
+ * Unlike other markdown-it plugins, mermaid doesn't need custom parsing rules
+ * because markdown-it already parses fenced code blocks. We just need to
+ * modify the renderer to add the appropriate class.
+ */
 import MarkdownIt from 'markdown-it';
 export interface MermaidPluginOptions {
     enable?: boolean;
 }
+/**
+ * markdown-it plugin interface
+ *
+ * Usage:
+ *   const md = new MarkdownIt();
+ *   md.use(mermaidPlugin, { enable: true });
+ *
+ * @param md - MarkdownIt instance
+ * @param options - Plugin options
+ */
 export declare function mermaidPlugin(md: MarkdownIt, options?: MermaidPluginOptions): void;
+/**
+ * Export as default for convenience
+ */
 export default mermaidPlugin;

package/dist/types/internal/domain/markdown/factory/it/plugins/tag-plugin.d.ts

@@ -1,24 +1,95 @@
+/**
+ * Standard markdown-it plugin for Obsidian-style inline tags
+ *
+ * Ported from Quartz v4: quartz/plugins/transformers/ofm.ts
+ *
+ * This plugin follows markdown-it best practices:
+ * 1. Inline parsing rule to recognize #tag syntax
+ * 2. Token-based representation (not HTML string manipulation)
+ * 3. Separate renderer rules for output
+ *
+ * Supports:
+ * - Simple tags: #idea, #note
+ * - Hierarchical tags: #plugin/emitter, #work/project/frontend
+ * - Unicode tags: #笔记, #项目/前端
+ * - Emoji tags: #🎉celebration
+ *
+ * IMPORTANT: This plugin also INJECTS tags into frontmatter.tags array
+ * This ensures tags are available in Foundry's taxonomy system
+ */
 import MarkdownIt from 'markdown-it';
+/**
+ * Internal state to track tags during parsing
+ */
 interface TagPluginState {
     tagBaseURL?: string;
     onTagFound?: (tag: string) => void;
 }
+/**
+ * Extend MarkdownIt type to include our custom state
+ */
 declare module 'markdown-it' {
     interface MarkdownIt {
         __tagPluginState?: TagPluginState;
     }
 }
+/**
+ * Tag metadata structure
+ */
 export interface TagMeta {
     rawTag: string;
     slugTag: string;
     url: string;
 }
+/**
+ * Tag regex from Quartz
+ * Source: quartz-src/quartz/plugins/transformers/ofm.ts lines 140-142
+ *
+ * (?<=^| )             -> lookbehind: tag must start at line beginning or after space
+ * #(...)               -> capturing group: tag must start with #
+ * (?:[-_\p{L}\p{Emoji}\p{M}\d])+       -> non-capturing group: alphanumeric + symbols (Unicode-aware)
+ * (?:\/[-_\p{L}\p{Emoji}\p{M}\d]+)*    -> optional: hierarchical tags separated by /
+ */
 export declare const tagRegex: RegExp;
+/**
+ * Options for tag plugin
+ */
 export interface TagPluginOptions {
+    /** Enable/disable tag parsing */
     enable?: boolean;
+    /** Base URL for tag links (default: "tags/") - relative path without leading slash */
     tagBaseURL?: string;
+    /** Callback to collect tags for frontmatter injection */
     onTagFound?: (tag: string) => void;
 }
+/**
+ * Slugify tag name (from Quartz util/path.ts)
+ *
+ * Normalizes tag to lowercase URL-safe format
+ * Handles hierarchical tags: "Plugin/Emitter" → "plugin/emitter"
+ *
+ * @param tag - Raw tag text
+ * @returns Normalized slug
+ */
 export declare function slugTag(tag: string): string;
+/**
+ * markdown-it plugin interface
+ *
+ * Usage:
+ *   const md = new MarkdownIt();
+ *   const collectedTags = new Set<string>();
+ *   md.use(tagPlugin, {
+ *     enable: true,
+ *     onTagFound: (tag) => collectedTags.add(tag)
+ *   });
+ *   const html = md.render(markdown);
+ *   // collectedTags now contains all inline tags found
+ *
+ * @param md - MarkdownIt instance
+ * @param options - Plugin options
+ */
 export declare function tagPlugin(md: MarkdownIt, options?: TagPluginOptions): void;
+/**
+ * Export as default for convenience
+ */
 export default tagPlugin;

package/dist/types/internal/domain/markdown/factory/it/plugins/wikilink-plugin.d.ts

@@ -1,4 +1,19 @@
+/**
+ * Standard markdown-it plugin for Obsidian-style wikilinks
+ *
+ * This plugin follows markdown-it best practices:
+ * 1. Inline parsing rule to recognize [[...]] syntax
+ * 2. Token-based representation (not HTML string manipulation)
+ * 3. Separate renderer rules for output
+ *
+ * Supports:
+ * - Regular wikilinks: [[Page]], [[Page#anchor]], [[Page|alias]]
+ * - Embeds: ![[image.png]], ![[video.mp4]], ![[Page]]
+ */
 import MarkdownIt from 'markdown-it';
+/**
+ * Wikilink metadata structure
+ */
 export interface WikilinkMeta {
     isEmbed: boolean;
     filepath: string;
@@ -6,7 +21,20 @@ export interface WikilinkMeta {
     alias?: string | undefined;
     url: string;
 }
+/**
+ * markdown-it plugin interface
+ *
+ * Usage:
+ *   const md = new MarkdownIt();
+ *   md.use(wikilinkPlugin);
+ *
+ * @param md - MarkdownIt instance
+ * @param options - Plugin options
+ */
 export declare function wikilinkPlugin(md: MarkdownIt, options?: {
     enable?: boolean;
 }): void;
+/**
+ * Export as default for convenience
+ */
 export default wikilinkPlugin;

package/dist/types/internal/domain/markdown/factory/it/plugins/wikilink.d.ts

@@ -1,8 +1,28 @@
+/**
+ * Wikilink processing utilities ported from Quartz
+ * Source: quartz-src/quartz/plugins/transformers/ofm.ts
+ *
+ * This module handles Obsidian-style wikilink syntax [[Page]] in markdown.
+ * Since MDFriday uses markdown-it (not remark), we do text-level preprocessing.
+ */
 export declare const externalLinkRegex: RegExp;
 export declare const wikilinkRegex: RegExp;
 export declare const tableRegex: RegExp;
 export declare const tableWikilinkRegex: RegExp;
+/**
+ * Pre-transform wikilinks at text level (before markdown parsing)
+ * Based on Quartz ofm.ts textTransform method (lines 161-209)
+ *
+ * This function:
+ * 1. Escapes wikilinks inside tables (pipe characters need escaping)
+ * 2. Normalizes wikilink format
+ * 3. Converts external links in wikilinks to regular markdown links
+ */
 export declare function preprocessWikilinks(src: string): string;
+/**
+ * Parse wikilink syntax into components
+ * Used by markdown-it renderer to convert [[Page]] to semantic HTML
+ */
 export interface WikilinkComponents {
     isEmbed: boolean;
     filepath: string;
@@ -11,6 +31,17 @@ export interface WikilinkComponents {
     url: string;
 }
 export declare function parseWikilink(match: string): WikilinkComponents | null;
+/**
+ * Get embed type from file extension
+ */
 export declare function getEmbedType(filepath: string): 'image' | 'video' | 'audio' | 'pdf' | 'transclude';
+/**
+ * Generate HTML for embedded content
+ * Based on Quartz ofm.ts lines 229-278
+ */
 export declare function generateEmbedHtml(components: WikilinkComponents): string;
+/**
+ * Check if a wikilink target exists in the site
+ * Used for broken link detection
+ */
 export declare function checkWikilinkExists(filepath: string, allSlugs: string[]): boolean;

package/dist/types/internal/domain/markdown/factory/it/tableofcontents.d.ts

@@ -1,10 +1,16 @@
 import { TocFragments, Header, Link, Paragraph } from '../../index';
+/**
+ * Fragment represents a single TOC entry
+ */
 export interface Fragment {
     id: string;
     text: string;
     level: number;
     children?: Fragment[];
 }
+/**
+ * TableOfContentsImpl implements TocFragments
+ */
 export declare class TableOfContentsImpl implements TocFragments {
     private fragments;
     constructor(fragments?: Fragment[]);
@@ -15,6 +21,9 @@ export declare class TableOfContentsImpl implements TocFragments {
     addFragment(fragment: Fragment): void;
     getFragments(): Fragment[];
 }
+/**
+ * HeaderImpl implements Header interface
+ */
 export declare class HeaderImpl implements Header {
     private _name;
     private _level;
@@ -31,6 +40,9 @@ export declare class HeaderImpl implements Header {
     addParagraph(paragraph: Paragraph): void;
     addListParagraph(paragraph: Paragraph): void;
 }
+/**
+ * LinkImpl implements Link interface
+ */
 export declare class LinkImpl implements Link {
     private _text;
     private _url;
@@ -38,11 +50,17 @@ export declare class LinkImpl implements Link {
     text(): string;
     url(): string;
 }
+/**
+ * ParagraphImpl implements Paragraph interface
+ */
 export declare class ParagraphImpl implements Paragraph {
     private _text;
     constructor(_text: string);
     text(): string;
 }
+/**
+ * TOC Builder utility class
+ */
 export declare class TOCBuilder {
     private fragments;
     private stack;
@@ -50,6 +68,9 @@ export declare class TOCBuilder {
     build(): TableOfContentsImpl;
     reset(): void;
 }
+/**
+ * Auto ID generation utilities
+ */
 export declare class AutoIDGenerator {
     private usedIds;
     generateID(text: string, type?: 'github' | 'github-ascii' | 'blackfriday'): string;

package/dist/types/internal/domain/markdown/factory/it/util/path.d.ts

@@ -1,12 +1,23 @@
+/**
+ * Path utilities ported from Quartz
+ * Source: quartz-src/quartz/util/path.ts
+ *
+ * This file contains path manipulation utilities for wikilink processing.
+ * These utilities are designed to work with Quartz-style slugs and paths.
+ */
 type SlugLike<T> = string & {
     __brand: T;
 };
+/** Cannot be relative and must have a file extension. */
 export type FilePath = SlugLike<"filepath">;
 export declare function isFilePath(s: string): s is FilePath;
+/** Cannot be relative and may not have leading or trailing slashes. It can have `index` as it's last segment. Use this wherever possible is it's the most 'general' interpretation of a slug. */
 export type FullSlug = SlugLike<"full">;
 export declare function isFullSlug(s: string): s is FullSlug;
+/** Shouldn't be a relative path and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path. */
 export type SimpleSlug = SlugLike<"simple">;
 export declare function isSimpleSlug(s: string): s is SimpleSlug;
+/** Can be found on `href`s but can also be constructed for client-side navigation (e.g. search and graph) */
 export type RelativeURL = SlugLike<"relative">;
 export declare function isRelativeURL(s: string): s is RelativeURL;
 export declare function isAbsoluteURL(s: string): boolean;