/**
* Standardized comment HTML construction.
*
* Used by Reddit, Hacker News, GitHub, and other extractors to produce
* consistent comment markup.
*
* Metadata format (in markdown): **author** · date · score
* - date is linked if a url is provided
* - score is omitted if not provided
*/
import { escapeHtml, isDangerousUrl } from './dom';
export interface CommentData {
/** Comment author name */
author: string;
/** Display date (e.g. "2025-01-15") */
date: string;
/** Comment body HTML */
content: string;
/** Nesting depth (0 = top-level). Omit for flat lists. */
depth?: number;
/** Score text (e.g. "42 points", "25 points") */
score?: string;
/** Permalink URL for the comment */
url?: string;
}
export interface QuotedPostData {
/** Author name */
author?: string;
/** Display date */
date?: string;
/** Post body HTML */
content: string;
/** Permalink URL */
url?: string;
}
/**
* Site identifiers used as the wrapper class alongside `post` / `comments`.
*
* Typed as a union rather than `string` so that adding an extractor is a compile
* error until the token is listed here. That matters because isExtractorClass()
* below is what keeps these classes alive through the attribute strip. A site
* that could pass any string would silently lose its wrapper class instead.
*/
export const SITE_TOKENS = [
'bluesky',
'discourse',
'github',
'gmail',
'hackernews',
'linkedin',
'lwn',
'mastodon',
'reddit',
'threads',
'twitter',
] as const;
export type SiteToken = typeof SITE_TOKENS[number];
const SITE_TOKEN_SET: Set = new Set(SITE_TOKENS);
// The rest of the class vocabulary the extractors emit: the comment tree above,
// the post wrappers in buildContentHtml, plus `post-text` (hackernews.ts),
// `quoted-post` (buildQuotedPost) and `x-article` (x-article.ts, x-oembed.ts).
//
// Conversation extractors' `message-*` classes are deliberately absent: those run
// their own nested Defuddle pass (see _conversation.ts), so the main pipeline has
// already stripped them before any of this applies.
const EXTRACTOR_CLASS_TOKEN = /^(?:comments?|posts?|quoted-post|x-article)(?:-[\w-]+)?$/;
/**
* Is this class token extractor-authored markup rather than something copied off
* the page? Used by the attribute strip to decide what survives. obsidian-clipper's
* reader keys its per-author colors, collapse buttons, and thread tracing off
* .comments / .comment / .comment-author / .comment-metadata.
*
* Lives here, next to the code that emits these classes, so the two cannot drift.
*/
export function isExtractorClass(token: string): boolean {
return SITE_TOKEN_SET.has(token) || EXTRACTOR_CLASS_TOKEN.test(token);
}
/**
* Build the full content HTML for a post with optional comments section.
* @param site - Site identifier for wrapper class (e.g. "reddit", "hackernews", "github")
* @param postContent - The main post body HTML
* @param comments - Pre-built comments HTML string (from buildCommentTree)
*/
export function buildContentHtml(site: SiteToken, postContent: string, comments: string): string {
return `
${comments ? `
` : ''}
`.trim();
}
/**
* Build a nested comment tree from a flat list of comments with depth.
* Uses elements to represent reply hierarchy.
*/
export function buildCommentTree(comments: CommentData[]): string {
const parts: string[] = [];
const blockquoteStack: number[] = [];
for (const comment of comments) {
const depth = comment.depth ?? 0;
if (depth === 0) {
while (blockquoteStack.length > 0) {
parts.push('
');
blockquoteStack.pop();
}
parts.push('');
blockquoteStack.push(0);
} else {
const currentDepth = blockquoteStack[blockquoteStack.length - 1] ?? -1;
if (depth < currentDepth) {
while (blockquoteStack.length > 0 && blockquoteStack[blockquoteStack.length - 1] >= depth) {
parts.push('
');
blockquoteStack.pop();
}
}
// Open a new level if needed (handles both deeper nesting
// and reopening after closing, e.g. depth 2 → 1 → 1)
const newCurrentDepth = blockquoteStack[blockquoteStack.length - 1] ?? -1;
if (depth > newCurrentDepth) {
parts.push('');
blockquoteStack.push(depth);
}
}
parts.push(buildComment(comment));
}
while (blockquoteStack.length > 0) {
parts.push('
');
blockquoteStack.pop();
}
return parts.join('');
}
/**
* Build a single comment div with metadata and content.
*
* Metadata order: author · date · score
* - date is wrapped in a link if url is provided
* - score is omitted if not provided
*/
export function buildComment(comment: CommentData): string {
const author = ``;
const safeUrl = comment.url && !isDangerousUrl(comment.url) ? comment.url : '';
const dateHtml = safeUrl
? ``
: ``;
const scoreHtml = comment.score
? ` · `
: '';
return ``;
}
/**
* Build a quoted/reposted post blockquote.
* Used by Twitter (quote tweets) and LinkedIn (reposts with commentary).
*/
export function buildQuotedPost(post: QuotedPostData): string {
let header = '';
if (post.author) {
header += `${escapeHtml(post.author)}`;
if (post.date) header += ` · ${escapeHtml(post.date)}`;
header += '
';
}
let footer = '';
if (post.url) {
const safeUrl = isDangerousUrl(post.url) ? '' : post.url;
if (safeUrl) {
footer = `\n${escapeHtml(safeUrl)}
`;
}
}
return `${header}${post.content}${footer}
`;
}
Comments
${comments}