@relvehq/agent-ready 0.0.0-stage → 0.3.0

package/dist/wp/relve-agent-ready/includes/class-relve-ar-converter.php

@@ -0,0 +1,762 @@
+<?php
+/**
+ * Converter: rendered post HTML -> Markdown, with DOMDocument only.
+ *
+ * The npm package uses turndown + GFM; this is a small equivalent for the
+ * markup WordPress produces (blocks, classic editor, page builders):
+ * headings, paragraphs, br, strong/em/del, links, images (alt + src), nested
+ * ul/ol, blockquote, pre/code (language from the class), inline code, GFM
+ * tables, hr. Scripts, styles, forms, iframes, nav, svg and hidden elements
+ * are dropped, as are shortcodes a page builder left behind. Whitespace is
+ * collapsed and URLs are made absolute against the page URL.
+ *
+ * Pure PHP (ext-dom): no WordPress calls.
+ *
+ * @package Relve_Agent_Ready
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * HTML to Markdown.
+ */
+class Relve_AR_Converter {
+
+	/** Elements removed with everything inside them. */
+	const JUNK = array( 'script', 'style', 'noscript', 'template', 'iframe', 'object', 'embed', 'svg', 'canvas', 'video', 'audio', 'form', 'input', 'button', 'select', 'textarea', 'label', 'nav', 'dialog', 'link', 'meta', 'head', 'title' );
+
+	/** Elements that start a new block. Everything else is inline. */
+	const BLOCKS = array( 'address', 'article', 'aside', 'blockquote', 'center', 'dd', 'details', 'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure', 'footer', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'li', 'main', 'ol', 'p', 'pre', 'section', 'summary', 'table', 'tbody', 'thead', 'tfoot', 'tr', 'td', 'th', 'ul', 'body', 'html', 'caption' );
+
+	/** Absolute URL of the page: base for relative links and images. @var string */
+	private $base;
+
+	/** Turn <h1> in the content into <h2> (the document has its own H1). @var bool */
+	private $demote_h1;
+
+	/** Shortcode names that appear with a closing tag somewhere. @var string[] */
+	private $closing_shortcodes = array();
+
+	/**
+	 * Convert HTML to Markdown.
+	 *
+	 * @param string $html    HTML fragment or document.
+	 * @param string $base    Absolute page URL.
+	 * @param array  $options { demote_h1: bool (default true) }.
+	 * @return string Markdown, trimmed ("" when nothing is left).
+	 */
+	public static function convert( $html, $base, $options = array() ) {
+		$c            = new self();
+		$c->base      = (string) $base;
+		$c->demote_h1 = ! isset( $options['demote_h1'] ) || $options['demote_h1'];
+		return $c->run( (string) $html );
+	}
+
+	/**
+	 * Parse, clean and render.
+	 *
+	 * @param string $html HTML.
+	 * @return string
+	 */
+	private function run( $html ) {
+		if ( '' === trim( $html ) || ! class_exists( 'DOMDocument' ) ) {
+			return '';
+		}
+		if ( preg_match_all( '#\[/([a-zA-Z][\w-]*)\]#', $html, $m ) ) {
+			$this->closing_shortcodes = array_unique( array_map( 'strtolower', $m[1] ) );
+		}
+
+		$doc      = new DOMDocument();
+		$previous = libxml_use_internal_errors( true );
+		$wrapped  = '<!DOCTYPE html><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body>' . $html . '</body></html>';
+		$loaded   = $doc->loadHTML( $wrapped, LIBXML_NONET | LIBXML_COMPACT );
+		libxml_clear_errors();
+		libxml_use_internal_errors( $previous );
+		if ( ! $loaded ) {
+			return '';
+		}
+		$body = $doc->getElementsByTagName( 'body' )->item( 0 );
+		if ( ! $body ) {
+			return '';
+		}
+		$this->clean( $body );
+		$blocks = $this->blocks( $body );
+		return trim( implode( "\n\n", $blocks ) );
+	}
+
+	// ── cleaning ──────────────────────────────────────────────────────────
+
+	/**
+	 * Remove junk, hidden elements and comments.
+	 *
+	 * @param DOMNode $root Root.
+	 * @return void
+	 */
+	private function clean( DOMNode $root ) {
+		$remove = array();
+		$walk   = function ( DOMNode $node ) use ( &$walk, &$remove ) {
+			foreach ( iterator_to_array( $node->childNodes ) as $child ) {
+				if ( XML_COMMENT_NODE === $child->nodeType || XML_PI_NODE === $child->nodeType ) {
+					$remove[] = $child;
+					continue;
+				}
+				if ( XML_ELEMENT_NODE !== $child->nodeType ) {
+					continue;
+				}
+				$tag = strtolower( $child->nodeName );
+				if ( in_array( $tag, self::JUNK, true ) || $this->is_hidden( $child ) ) {
+					$remove[] = $child;
+					continue;
+				}
+				$walk( $child );
+			}
+		};
+		$walk( $root );
+		foreach ( $remove as $node ) {
+			if ( $node->parentNode ) {
+				$node->parentNode->removeChild( $node );
+			}
+		}
+	}
+
+	/**
+	 * Hidden by attribute or inline style.
+	 *
+	 * @param DOMElement $el Element.
+	 * @return bool
+	 */
+	private function is_hidden( $el ) {
+		if ( $el->hasAttribute( 'hidden' ) ) {
+			return true;
+		}
+		if ( 'true' === strtolower( $el->getAttribute( 'aria-hidden' ) ) ) {
+			return true;
+		}
+		$style = strtolower( $el->getAttribute( 'style' ) );
+		return '' !== $style && (bool) preg_match( '/display\s*:\s*none|visibility\s*:\s*hidden/', $style );
+	}
+
+	// ── blocks ────────────────────────────────────────────────────────────
+
+	/**
+	 * Render a container's children as a list of Markdown blocks. Runs of
+	 * inline content become paragraphs, so page-builder div soup reads as
+	 * paragraphs.
+	 *
+	 * @param DOMNode $parent Container.
+	 * @return string[]
+	 */
+	private function blocks( DOMNode $parent ) {
+		$out    = array();
+		$inline = '';
+		foreach ( $parent->childNodes as $child ) {
+			if ( $this->is_block( $child ) ) {
+				$this->flush( $inline, $out );
+				$inline = '';
+				foreach ( $this->block( $child ) as $b ) {
+					if ( '' !== trim( $b ) ) {
+						$out[] = $b;
+					}
+				}
+			} else {
+				$inline .= $this->inline( $child );
+			}
+		}
+		$this->flush( $inline, $out );
+		return $out;
+	}
+
+	/**
+	 * Turn collected inline Markdown into a paragraph block.
+	 *
+	 * @param string   $inline Inline Markdown.
+	 * @param string[] $out    Blocks (appended to).
+	 * @return void
+	 */
+	private function flush( $inline, &$out ) {
+		$p = $this->paragraph( $inline );
+		if ( '' !== $p ) {
+			$out[] = $p;
+		}
+	}
+
+	/**
+	 * Tidy a paragraph: trim each line, collapse spaces, escape characters
+	 * that would start a block at the beginning of a line.
+	 *
+	 * @param string $text Inline Markdown.
+	 * @return string
+	 */
+	private function paragraph( $text ) {
+		$lines = array();
+		foreach ( explode( "\n", $text ) as $line ) {
+			$line = trim( preg_replace( '/ {2,}/', ' ', $line ) );
+			if ( '' === $line ) {
+				continue;
+			}
+			$lines[] = $this->escape_line_start( $line );
+		}
+		return implode( "\n", $lines );
+	}
+
+	/**
+	 * Escape a leading #, >, -, +, "1." that would change the block type.
+	 *
+	 * @param string $line Line.
+	 * @return string
+	 */
+	private function escape_line_start( $line ) {
+		if ( preg_match( '/^(#{1,6}\s|>|[-+]\s|=+\s*$|-{3,}\s*$)/', $line ) ) {
+			return '\\' . $line;
+		}
+		if ( preg_match( '/^(\d+)\.(\s)/', $line ) ) {
+			return preg_replace( '/^(\d+)\./', '$1\\.', $line );
+		}
+		return $line;
+	}
+
+	/**
+	 * Does this node start a block?
+	 *
+	 * @param DOMNode $node Node.
+	 * @return bool
+	 */
+	private function is_block( DOMNode $node ) {
+		return XML_ELEMENT_NODE === $node->nodeType && in_array( strtolower( $node->nodeName ), self::BLOCKS, true );
+	}
+
+	/**
+	 * Render one block element.
+	 *
+	 * @param DOMElement $el Element.
+	 * @return string[]
+	 */
+	private function block( DOMElement $el ) {
+		$tag = strtolower( $el->nodeName );
+		switch ( $tag ) {
+			case 'h1':
+			case 'h2':
+			case 'h3':
+			case 'h4':
+			case 'h5':
+			case 'h6':
+				$level = (int) substr( $tag, 1 );
+				if ( 1 === $level && $this->demote_h1 ) {
+					$level = 2;
+				}
+				$text = $this->one_line( $this->inline_children( $el ) );
+				return '' === $text ? array() : array( str_repeat( '#', $level ) . ' ' . $text );
+			case 'p':
+			case 'dt':
+			case 'summary':
+			case 'caption':
+				$p = $this->paragraph( $this->inline_children( $el ) );
+				if ( 'dt' === $tag && '' !== $p ) {
+					$p = '**' . $this->one_line( $p ) . '**';
+				}
+				return array( $p );
+			case 'hr':
+				return array( '---' );
+			case 'pre':
+				return array( $this->code_block( $el ) );
+			case 'blockquote':
+				$inner = implode( "\n\n", $this->blocks( $el ) );
+				if ( '' === trim( $inner ) ) {
+					return array();
+				}
+				$lines = array();
+				foreach ( explode( "\n", $inner ) as $line ) {
+					$lines[] = '' === $line ? '>' : '> ' . $line;
+				}
+				return array( implode( "\n", $lines ) );
+			case 'ul':
+			case 'ol':
+				return array( $this->list_block( $el, 'ol' === $tag ) );
+			case 'table':
+				return array( $this->table( $el ) );
+			case 'li':
+				// A stray <li> outside a list: render it as a one-item list.
+				return array( $this->list_item( $el, '- ' ) );
+			default:
+				return $this->blocks( $el );
+		}
+	}
+
+	/**
+	 * Fenced code block. Language from "language-x" / "lang-x" / "brush: x".
+	 *
+	 * @param DOMElement $pre The <pre>.
+	 * @return string
+	 */
+	private function code_block( DOMElement $pre ) {
+		$classes = $pre->getAttribute( 'class' ) . ' ' . $pre->getAttribute( 'data-lang' );
+		foreach ( $pre->childNodes as $child ) {
+			if ( XML_ELEMENT_NODE === $child->nodeType && 'code' === strtolower( $child->nodeName ) ) {
+				$classes .= ' ' . $child->getAttribute( 'class' ) . ' ' . $child->getAttribute( 'data-lang' );
+			}
+		}
+		$lang = '';
+		if ( preg_match( '/(?:^|\s)(?:language|lang)-([A-Za-z0-9_+#.-]+)/', $classes, $m ) ) {
+			$lang = $m[1];
+		} elseif ( preg_match( '/brush:\s*([A-Za-z0-9_+#-]+)/', $classes, $m ) ) {
+			$lang = $m[1];
+		} elseif ( preg_match( '/^\s*([A-Za-z0-9_+#-]+)\s*$/', $pre->getAttribute( 'data-lang' ), $m ) ) {
+			$lang = $m[1];
+		}
+		$code = str_replace( array( "\r\n", "\r" ), "\n", $pre->textContent );
+		$code = preg_replace( '/^\n/', '', $code );
+		$code = rtrim( $code, "\n" );
+		$fence = '```';
+		if ( preg_match_all( '/`{3,}/', $code, $m ) ) {
+			$longest = max( array_map( 'strlen', $m[0] ) );
+			$fence   = str_repeat( '`', $longest + 1 );
+		}
+		return $fence . strtolower( $lang ) . "\n" . $code . "\n" . $fence;
+	}
+
+	/**
+	 * A ul / ol. Nested lists are indented under their item.
+	 *
+	 * @param DOMElement $list    The list.
+	 * @param bool       $ordered Ordered?
+	 * @return string
+	 */
+	private function list_block( DOMElement $list, $ordered ) {
+		$n     = $ordered && is_numeric( $list->getAttribute( 'start' ) ) ? (int) $list->getAttribute( 'start' ) : 1;
+		$items = array();
+		$loose = false;
+		foreach ( $list->childNodes as $child ) {
+			if ( XML_ELEMENT_NODE !== $child->nodeType ) {
+				continue;
+			}
+			$tag = strtolower( $child->nodeName );
+			if ( 'ul' === $tag || 'ol' === $tag ) {
+				// Invalid but common: a list directly inside a list. Attach it
+				// to the previous item.
+				$nested = $this->indent( $this->list_block( $child, 'ol' === $tag ), '  ' );
+				if ( $items ) {
+					$items[ count( $items ) - 1 ] .= "\n" . $nested;
+				} else {
+					$items[] = $nested;
+				}
+				continue;
+			}
+			$marker = $ordered ? $n . '. ' : '- ';
+			$item   = $this->list_item( $child, $marker );
+			if ( '' === $item ) {
+				continue;
+			}
+			foreach ( $child->childNodes as $grand ) {
+				if ( XML_ELEMENT_NODE === $grand->nodeType && 'p' === strtolower( $grand->nodeName ) ) {
+					$loose = true;
+				}
+			}
+			$items[] = $item;
+			++$n;
+		}
+		return implode( $loose ? "\n\n" : "\n", $items );
+	}
+
+	/**
+	 * One list item: marker on the first line, the rest indented to match.
+	 *
+	 * @param DOMElement $li     The item.
+	 * @param string     $marker "- " or "N. ".
+	 * @return string
+	 */
+	private function list_item( DOMElement $li, $marker ) {
+		$blocks = $this->blocks( $li );
+		if ( ! $blocks ) {
+			return '';
+		}
+		$tight = true;
+		foreach ( $li->childNodes as $c ) {
+			if ( XML_ELEMENT_NODE === $c->nodeType && 'p' === strtolower( $c->nodeName ) ) {
+				$tight = false;
+			}
+		}
+		$content = implode( $tight ? "\n" : "\n\n", $blocks );
+		$pad     = str_repeat( ' ', strlen( $marker ) );
+		$lines   = explode( "\n", $content );
+		$out     = $marker . array_shift( $lines );
+		foreach ( $lines as $line ) {
+			$out .= "\n" . ( '' === $line ? '' : $pad . $line );
+		}
+		return $out;
+	}
+
+	/**
+	 * Indent every non-empty line.
+	 *
+	 * @param string $text Text.
+	 * @param string $pad  Indent.
+	 * @return string
+	 */
+	private function indent( $text, $pad ) {
+		$lines = explode( "\n", $text );
+		foreach ( $lines as $i => $line ) {
+			if ( '' !== $line ) {
+				$lines[ $i ] = $pad . $line;
+			}
+		}
+		return implode( "\n", $lines );
+	}
+
+	/**
+	 * GFM table. The first row is the header row (GFM needs one).
+	 *
+	 * @param DOMElement $table The table.
+	 * @return string
+	 */
+	private function table( DOMElement $table ) {
+		$rows    = array();
+		$caption = '';
+		$collect = function ( DOMNode $node ) use ( &$collect, &$rows, &$caption ) {
+			foreach ( $node->childNodes as $child ) {
+				if ( XML_ELEMENT_NODE !== $child->nodeType ) {
+					continue;
+				}
+				$tag = strtolower( $child->nodeName );
+				if ( 'caption' === $tag ) {
+					$caption = $this->one_line( $this->inline_children( $child ) );
+				} elseif ( 'thead' === $tag || 'tbody' === $tag || 'tfoot' === $tag ) {
+					$collect( $child );
+				} elseif ( 'tr' === $tag ) {
+					$cells = array();
+					foreach ( $child->childNodes as $cell ) {
+						if ( XML_ELEMENT_NODE === $cell->nodeType && in_array( strtolower( $cell->nodeName ), array( 'td', 'th' ), true ) ) {
+							$cells[] = $this->cell( $cell );
+						}
+					}
+					if ( $cells ) {
+						$rows[] = $cells;
+					}
+				}
+			}
+		};
+		$collect( $table );
+		if ( ! $rows ) {
+			return $caption;
+		}
+		$width = 0;
+		foreach ( $rows as $r ) {
+			$width = max( $width, count( $r ) );
+		}
+		$lines = array();
+		foreach ( $rows as $i => $r ) {
+			$r       = array_pad( $r, $width, '' );
+			$lines[] = '| ' . implode( ' | ', $r ) . ' |';
+			if ( 0 === $i ) {
+				$lines[] = '|' . str_repeat( ' --- |', $width );
+			}
+		}
+		$out = implode( "\n", $lines );
+		return '' !== $caption ? $caption . "\n\n" . $out : $out;
+	}
+
+	/**
+	 * One table cell on one line, pipes escaped.
+	 *
+	 * @param DOMElement $cell Cell.
+	 * @return string
+	 */
+	private function cell( DOMElement $cell ) {
+		$text = implode( ' ', $this->blocks( $cell ) );
+		$text = $this->one_line( $text );
+		return str_replace( '|', '\\|', $text );
+	}
+
+	// ── inline ────────────────────────────────────────────────────────────
+
+	/**
+	 * Inline Markdown for all children of a node.
+	 *
+	 * @param DOMNode $node Node.
+	 * @return string
+	 */
+	private function inline_children( DOMNode $node ) {
+		$out = '';
+		foreach ( $node->childNodes as $child ) {
+			$out .= $this->inline( $child );
+		}
+		return $out;
+	}
+
+	/**
+	 * Inline Markdown for one node.
+	 *
+	 * @param DOMNode $node Node.
+	 * @return string
+	 */
+	private function inline( DOMNode $node ) {
+		if ( XML_TEXT_NODE === $node->nodeType || XML_CDATA_SECTION_NODE === $node->nodeType ) {
+			return $this->text( $node->nodeValue );
+		}
+		if ( XML_ELEMENT_NODE !== $node->nodeType ) {
+			return '';
+		}
+		$tag = strtolower( $node->nodeName );
+		switch ( $tag ) {
+			case 'br':
+				return "\n";
+			case 'strong':
+			case 'b':
+				return $this->wrap( $this->inline_children( $node ), '**' );
+			case 'em':
+			case 'i':
+			case 'cite':
+				return $this->wrap( $this->inline_children( $node ), '_' );
+			case 'del':
+			case 's':
+			case 'strike':
+				return $this->wrap( $this->inline_children( $node ), '~~' );
+			case 'code':
+			case 'kbd':
+			case 'samp':
+				return $this->inline_code( $node->textContent );
+			case 'a':
+				return $this->link( $node );
+			case 'img':
+				return $this->image( $node );
+			case 'pre':
+				return ' ' . $this->inline_code( $node->textContent ) . ' ';
+			default:
+				if ( $this->is_block( $node ) ) {
+					// A block inside inline context (e.g. a div in a link):
+					// keep its text on the line.
+					return ' ' . $this->inline_children( $node ) . ' ';
+				}
+				return $this->inline_children( $node );
+		}
+	}
+
+	/**
+	 * Escape text and drop shortcode leftovers.
+	 *
+	 * @param string $text Raw text.
+	 * @return string
+	 */
+	private function text( $text ) {
+		$text = str_replace( "\xC2\xA0", ' ', (string) $text );
+		$text = $this->strip_shortcodes( $text );
+		$text = preg_replace( '/\s+/u', ' ', $text );
+		if ( null === $text ) {
+			return '';
+		}
+		return preg_replace( '/([\\\\`*_\[\]])/', '\\\\$1', $text );
+	}
+
+	/**
+	 * Remove shortcodes a builder left unrendered: any [/name], any
+	 * [name attr=...], and a bare [name] only when [/name] also appears (so
+	 * "[sic]" or "[1]" in prose survive).
+	 *
+	 * @param string $text Text.
+	 * @return string
+	 */
+	private function strip_shortcodes( $text ) {
+		if ( false === strpos( $text, '[' ) ) {
+			return $text;
+		}
+		$closing = $this->closing_shortcodes;
+		$result  = preg_replace_callback(
+			'#\[(/?)([a-zA-Z][\w-]*)((?:\s[^\[\]]*)?)/?\]#',
+			function ( $m ) use ( $closing ) {
+				if ( '/' === $m[1] ) {
+					return '';
+				}
+				if ( false !== strpos( $m[3], '=' ) ) {
+					return '';
+				}
+				return in_array( strtolower( $m[2] ), $closing, true ) ? '' : $m[0];
+			},
+			$text
+		);
+		return null === $result ? $text : $result;
+	}
+
+	/**
+	 * Wrap inline content in a delimiter, keeping outer spaces outside.
+	 *
+	 * @param string $inner Inline Markdown.
+	 * @param string $mark  Delimiter.
+	 * @return string
+	 */
+	private function wrap( $inner, $mark ) {
+		if ( '' === trim( $inner ) ) {
+			return $inner;
+		}
+		preg_match( '/^(\s*)(.*?)(\s*)$/s', $inner, $m );
+		return $m[1] . $mark . $m[2] . $mark . $m[3];
+	}
+
+	/**
+	 * Inline code span with a fence longer than any backtick run inside.
+	 *
+	 * @param string $code Raw code.
+	 * @return string
+	 */
+	private function inline_code( $code ) {
+		$code = preg_replace( '/\s*\n\s*/', ' ', str_replace( "\xC2\xA0", ' ', (string) $code ) );
+		if ( '' === trim( $code ) ) {
+			return '';
+		}
+		$fence = '`';
+		if ( preg_match_all( '/`+/', $code, $m ) ) {
+			$fence = str_repeat( '`', max( array_map( 'strlen', $m[0] ) ) + 1 );
+		}
+		$pad = ( '`' === substr( $code, 0, 1 ) || '`' === substr( $code, -1 ) ) ? ' ' : '';
+		return $fence . $pad . $code . $pad . $fence;
+	}
+
+	/**
+	 * A link. javascript: links and links without text are unwrapped.
+	 *
+	 * @param DOMElement $a Anchor.
+	 * @return string
+	 */
+	private function link( DOMElement $a ) {
+		$inner = $this->one_line( $this->inline_children( $a ) );
+		$href  = trim( $a->getAttribute( 'href' ) );
+		if ( '' === $href ) {
+			return $inner;
+		}
+		$abs = self::absolute( $href, $this->base );
+		if ( null === $abs || preg_match( '/^\s*(javascript|data|vbscript):/i', $abs ) ) {
+			return $inner;
+		}
+		if ( '' === $inner ) {
+			return '';
+		}
+		return '[' . $inner . '](' . self::url_for_markdown( $abs ) . ')';
+	}
+
+	/**
+	 * An image: alt + absolute src. Lazy-load attributes are preferred over a
+	 * data: placeholder; emoji images become their alt text.
+	 *
+	 * @param DOMElement $img Image.
+	 * @return string
+	 */
+	private function image( DOMElement $img ) {
+		$alt = $this->one_line( str_replace( "\xC2\xA0", ' ', $img->getAttribute( 'alt' ) ) );
+		if ( preg_match( '/(^|\s)(emoji|wp-smiley)(\s|$)/', $img->getAttribute( 'class' ) ) ) {
+			return $alt;
+		}
+		$src = '';
+		foreach ( array( 'data-lazy-src', 'data-src', 'src' ) as $attr ) {
+			$v = trim( $img->getAttribute( $attr ) );
+			if ( '' !== $v && ! preg_match( '/^data:/i', $v ) ) {
+				$src = $v;
+				break;
+			}
+		}
+		if ( '' === $src ) {
+			return '';
+		}
+		$abs = self::absolute( $src, $this->base );
+		if ( null === $abs || ! preg_match( '#^https?://#i', $abs ) ) {
+			return '';
+		}
+		$alt = str_replace( array( '[', ']' ), array( '\\[', '\\]' ), $alt );
+		return '![' . $alt . '](' . self::url_for_markdown( $abs ) . ')';
+	}
+
+	/**
+	 * Collapse whitespace to one line.
+	 *
+	 * @param string $s Text.
+	 * @return string
+	 */
+	private function one_line( $s ) {
+		return trim( preg_replace( '/\s+/u', ' ', (string) $s ) );
+	}
+
+	// ── URLs ──────────────────────────────────────────────────────────────
+
+	/**
+	 * Spaces and parentheses would end a Markdown link destination.
+	 *
+	 * @param string $url URL.
+	 * @return string
+	 */
+	public static function url_for_markdown( $url ) {
+		return str_replace( array( ' ', '(', ')' ), array( '%20', '%28', '%29' ), $url );
+	}
+
+	/**
+	 * Resolve $href against $base (RFC 3986, enough for HTML attributes).
+	 *
+	 * @param string $href Reference.
+	 * @param string $base Absolute base URL.
+	 * @return string|null
+	 */
+	public static function absolute( $href, $base ) {
+		$href = trim( (string) $href );
+		if ( '' === $href ) {
+			return null;
+		}
+		if ( preg_match( '#^[a-zA-Z][a-zA-Z0-9+.-]*:#', $href ) ) {
+			return $href;
+		}
+		$b = parse_url( (string) $base );
+		if ( ! $b || empty( $b['scheme'] ) || empty( $b['host'] ) ) {
+			return null;
+		}
+		$origin = $b['scheme'] . '://' . $b['host'] . ( isset( $b['port'] ) ? ':' . $b['port'] : '' );
+		if ( 0 === strpos( $href, '//' ) ) {
+			return $b['scheme'] . ':' . $href;
+		}
+		$base_path  = isset( $b['path'] ) && '' !== $b['path'] ? $b['path'] : '/';
+		$base_query = isset( $b['query'] ) ? '?' . $b['query'] : '';
+		if ( '#' === $href[0] ) {
+			return $origin . $base_path . $base_query . $href;
+		}
+		if ( '?' === $href[0] ) {
+			return $origin . $base_path . $href;
+		}
+		if ( '/' === $href[0] ) {
+			$path = $href;
+		} else {
+			$dir  = substr( $base_path, 0, strrpos( $base_path, '/' ) + 1 );
+			$path = $dir . $href;
+		}
+		// Split off query / fragment before removing dot segments.
+		$suffix = '';
+		$cut    = strcspn( $path, '?#' );
+		if ( $cut < strlen( $path ) ) {
+			$suffix = substr( $path, $cut );
+			$path   = substr( $path, 0, $cut );
+		}
+		return $origin . self::remove_dot_segments( $path ) . $suffix;
+	}
+
+	/**
+	 * RFC 3986 5.2.4.
+	 *
+	 * @param string $path Path.
+	 * @return string
+	 */
+	private static function remove_dot_segments( $path ) {
+		$out = array();
+		foreach ( explode( '/', $path ) as $i => $seg ) {
+			if ( '.' === $seg ) {
+				continue;
+			}
+			if ( '..' === $seg ) {
+				if ( count( $out ) > 1 ) {
+					array_pop( $out );
+				}
+				continue;
+			}
+			$out[] = $seg;
+		}
+		$result = implode( '/', $out );
+		if ( preg_match( '#/\.\.?$#', $path ) ) {
+			$result .= '/';
+		}
+		return '' === $result || '/' !== $result[0] ? '/' . ltrim( $result, '/' ) : $result;
+	}
+}