Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

9.3 KB
Raw Blame
import { marked } from 'marked';
import DOMPurify from 'dompurify';

// Shipped documentation lives at /docs/<path>.md as a static asset. The
// rendered viewer is the same path without the .md suffix, which cannot
// collide because every shipped file ends in .md and anything else falls
// through to the SPA.
export const DOC_ROUTE_PREFIX = '/docs';

export const docRouteForPath = (docPath: string): string =>
  `${DOC_ROUTE_PREFIX}/${normalizeDocPath(docPath)}`;

export const docAssetUrlForPath = (docPath: string): string =>
  `${DOC_ROUTE_PREFIX}/${normalizeDocPath(docPath)}.md`;

/** Strips a leading slash, a docs prefix, and a trailing .md suffix. */
export function normalizeDocPath(raw: string): string {
  let value = (raw ?? '').trim();
  value = value.replace(/^\/+/, '');
  if (value.toLowerCase().startsWith('docs/')) value = value.slice('docs/'.length);
  value = value.replace(/\.md$/i, '');
  value = value.replace(/^\/+|\/+$/g, '');
  return value;
}

/**
 * Resolves a relative markdown link against the document containing it.
 *
 * Repo docs are written for GitHub, where docs/ sits inside the repository, so
 * they contain links such as `../SECURITY.md` that climb above the docs root.
 * Under the shipped /docs root there is nothing above, and those files are
 * shipped flat alongside the rest, so a climb that escapes the root is clamped
 * to it rather than left dangling.
 */
export function resolveDocLink(currentDocPath: string, href: string): string | null {
  const trimmed = (href ?? '').trim();
  if (!trimmed || !/\.md(?:[?#].*)?$/i.test(trimmed)) return null;
  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null; // absolute URL, not ours

  const [pathPart, fragment = ''] = splitFragment(trimmed);
  const baseSegments = normalizeDocPath(currentDocPath).split('/').slice(0, -1);
  const segments = pathPart.startsWith('/') ? [] : [...baseSegments];

  for (const segment of pathPart.replace(/^\/+/, '').split('/')) {
    if (!segment || segment === '.') continue;
    if (segment === '..') {
      segments.pop();
      continue;
    }
    segments.push(segment);
  }

  const resolved = normalizeDocPath(segments.join('/'));
  if (!resolved) return null;
  return `${docRouteForPath(resolved)}${fragment}`;
}

function splitFragment(value: string): [string, string] {
  const index = value.search(/[?#]/);
  if (index < 0) return [value, ''];
  return [value.slice(0, index), value.slice(index)];
}

/**
 * Renders shipped documentation markdown to sanitised HTML.
 *
 * Deliberately not the AI chat's renderMarkdown: that one sets `breaks: true`
 * globally, which turns every hard-wrapped line in a normal document into a
 * visible break, and pins hrefs to http/https/mailto, which strips the
 * relative links that hold the documentation set together. Options are passed
 * per parse call here so neither renderer can disturb the other.
 */
export function renderDocMarkdown(markdown: string, currentDocPath: string): string {
  const source = typeof markdown === 'string' ? markdown : '';
  const rawHtml = marked.parse(source, { gfm: true, breaks: false, async: false }) as string;

  const sanitized = DOMPurify.sanitize(rawHtml, {
    ALLOWED_TAGS: [
      'p',
      'br',
      'strong',
      'em',
      'b',
      'i',
      'u',
      'del',
      'code',
      'pre',
      'blockquote',
      'ul',
      'ol',
      'li',
      'h1',
      'h2',
      'h3',
      'h4',
      'h5',
      'h6',
      'a',
      'hr',
      'table',
      'thead',
      'tbody',
      'tr',
      'th',
      'td',
      'span',
      'div',
      'img',
      'details',
      'summary',
    ],
    // Relative hrefs must survive so intra-document links keep working; they
    // are rewritten to viewer routes below. 'class' stays out for the same
    // UI-redressing reason the chat renderer excludes it.
    ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'id', 'align'],
    ALLOWED_URI_REGEXP: /^(?:https?:|mailto:|[^a-z0-9+.-]|[^:]*$)/i,
  });

  return rewriteDocLinks(sanitized, currentDocPath);
}

/**
 * Wraps tables in their own horizontal scroll container.
 *
 * Making the table itself `display: block; overflow-x: auto` is not enough:
 * its rows still lay out past the block box, so a wide table pushes the whole
 * page into horizontal scrolling on a phone. A wrapping element is what
 * actually contains the overflow.
 */
export function wrapTables(container: HTMLElement): void {
  container.querySelectorAll('table').forEach((table) => {
    // Sanitised Markdown has no author-controlled roles/scope. Assign trusted
    // column semantics to header cells: browsers otherwise expose these THs
    // as ordinary cells, leaving readers without table header associations.
    table.querySelectorAll('thead th').forEach((header) => header.setAttribute('scope', 'col'));
    const parent = table.parentElement;
    if (parent?.dataset?.docTableScroll !== undefined) return;
    const wrapper = window.document.createElement('div');
    wrapper.dataset.docTableScroll = '';
    wrapper.className = 'max-w-full overflow-x-auto';
    table.replaceWith(wrapper);
    wrapper.appendChild(table);
  });
}

/**
 * GitHub-compatible heading slug: lower-cased, punctuation removed and spaces
 * replaced with hyphens. This mirrors the anchors GitHub generates for
 * repository headings so links such as `#resource-maintenance` resolve in the
 * shipped viewer. It is implemented locally, without a runtime dependency, so
 * the documentation route adds no bundle weight beyond the renderer it already
 * ships.
 */
function githubHeadingSlug(value: string): string {
  return value
    .toLowerCase()
    .replace(/[^\p{L}\p{N}\p{M}\p{Pc} -]/gu, '')
    .replace(/ /g, '-');
}

/**
 * Points intra-documentation links at the viewer instead of the raw asset, so
 * following one renders the next document rather than downloading its source.
 */
export function rewriteDocLinks(html: string, currentDocPath: string): string {
  if (typeof document === 'undefined') return html;
  const container = document.createElement('div');
  container.innerHTML = html;
  // Repository links use GitHub heading fragments. Marked emits headings
  // without IDs, so generate them from sanitized text and keep duplicate
  // headings distinct without colliding with explicit document anchors. The
  // occurrence counter is document-local, matching GitHub's per-document
  // duplicate numbering.
  const occurrences: Record<string, number> = Object.create(null);
  const slug = (text: string): string => {
    const base = githubHeadingSlug(text);
    if (Object.prototype.hasOwnProperty.call(occurrences, base)) {
      occurrences[base] += 1;
      return `${base}-${occurrences[base]}`;
    }
    occurrences[base] = 0;
    return base;
  };
  const ids = new Set(Array.from(container.querySelectorAll('[id]'), (element) => element.id));
  container.querySelectorAll('h1, h2, h3, h4, h5, h6').forEach((heading) => {
    if (heading.id) return;
    let id = slug(heading.textContent ?? '');
    while (ids.has(id)) id = slug(heading.textContent ?? '');
    heading.id = id;
    ids.add(id);
  });
  wrapTables(container);

  container.querySelectorAll('a[href]').forEach((anchor) => {
    const href = anchor.getAttribute('href') ?? '';
    const resolved = resolveDocLink(currentDocPath, href);
    if (resolved) {
      anchor.setAttribute('href', resolved);
      anchor.setAttribute('data-doc-link', '');
      anchor.removeAttribute('target');
      anchor.removeAttribute('rel');
      return;
    }
    if (/^https?:/i.test(href)) {
      anchor.setAttribute('target', '_blank');
      anchor.setAttribute('rel', 'noopener noreferrer');
    }
  });

  return container.innerHTML;
}

/** Follow a fragment after the asynchronously loaded document is rendered. */
export function scrollToDocFragment(container: HTMLElement, hash: string): void {
  if (!hash || hash === '#') return;
  let id: string;
  try {
    id = decodeURIComponent(hash.replace(/^#/, ''));
  } catch {
    return;
  }
  const target = Array.from(container.querySelectorAll<HTMLElement>('[id]')).find(
    (element) => element.id === id,
  );
  if (!target) return;
  target.tabIndex = -1;
  target.scrollIntoView({ block: 'start' });
  target.focus({ preventScroll: true });
}

/** First level-one heading, used as the document title. */
export function extractDocTitle(markdown: string, fallback: string): string {
  const index = leadingTitleLineIndex(markdown);
  if (index < 0) return fallback;
  return /^#\s+(.+?)\s*$/.exec((markdown ?? '').split('\n')[index])![1].trim();
}

/**
 * Removes the leading level-one heading, which the viewer promotes into the
 * page header. Leaving it in renders the document title twice.
 */
export function stripLeadingTitle(markdown: string): string {
  const lines = (markdown ?? '').split('\n');
  const index = leadingTitleLineIndex(markdown);
  if (index < 0) return markdown ?? '';
  lines.splice(index, 1);
  while (lines.length && lines[0].trim() === '') lines.shift();
  return lines.join('\n');
}

/**
 * Index of the document's own title line, meaning a level-one heading that
 * appears before any other content. A `# ` further down belongs to the body.
 */
function leadingTitleLineIndex(markdown: string): number {
  const lines = (markdown ?? '').split('\n');
  for (let index = 0; index < lines.length; index += 1) {
    const line = lines[index];
    if (line.trim() === '') continue;
    return /^#\s+.+/.test(line) ? index : -1;
  }
  return -1;
}