Embedded pieces of HTML, such as comments, the descriptions in feeds or the fields of a CMS, read into Hiccup and rendered from there.
TODO: an optional report of what parsing discarded and sanitizing removed, e.g. in metadata, so that a validator can tell the author of the HTML what a client won't show.
TODO: in the browser, an option to parse with the browser's own DOMParser and read its DOM as Hiccup, as hickory does, which would keep the tokenizer, the tree builder and the table of character references out of the bundle. It would come at a cost:
Embedded pieces of HTML, such as comments, the descriptions in feeds or the fields of a CMS, read into Hiccup and rendered from there. TODO: an optional report of what parsing discarded and sanitizing removed, e.g. in metadata, so that a validator can tell the author of the HTML what a client won't show. TODO: in the browser, an option to parse with the browser's own DOMParser and read its DOM as Hiccup, as hickory does, which would keep the tokenizer, the tree builder and the table of character references out of the bundle. It would come at a cost: - the result could differ from the JVM's and Node's, since a browser follows every rule of tree construction, e.g. it carries formatting on past a misnested end tag, moves the content of tables, and rearranges the html, head and body of a whole page - Node has no DOM, so the tokenizer would still be needed there - DOMParser reads a whole document, so a fragment would be the children of its body, and :max-depth would have to be applied while reading the DOM
The attributes that are safe to render, by element.
The attributes that are safe to render, by element.
The schemes of the URLs that are safe to keep or show as links.
The schemes of the URLs that are safe to keep or show as links.
The elements that are safe to render.
The elements that are safe to render.
(base-url x)(base-url x opts)The URL that the links of the page x are relative to, by opts: the
href of its first base element that has one, resolved against :base-url,
the URL of the page, or else :base-url.
The URL that the links of the page `x` are relative to, by `opts`: the href of its first base element that has one, resolved against :base-url, the URL of the page, or else :base-url.
The default of each option. Most are vars of the same name, and the others are:
The default of each option. Most are vars of the same name, and the others are: - :base-url, the URL of the page that the HTML came from, which each URL is resolved against - :url-fn, a function of a URL, once it's resolved, that gives the URL to keep, or nil - :element-fn, a function of an element that's kept, which gives the Hiccup to put in its place - :trusted-element-fn?, true to keep what :element-fn gives unchecked - :links?, true to put the URL of each link after it in plain text - :quirks?, true to read a C1 control character as windows-1252 in text and Markdown, a repair that the HTML Standard doesn't make - :shorthand?, true to read a tag of Hiccup such as :p.x as a p with a class, or false to read each tag as it's written, as in the Hiccup that parse gives - :plain-text?, true to read a string as plain text even when it holds a tag, with its character references kept as they're written - :rel, a link type, for links to take only the elements whose rel has it - :body?, false for links to take only the elements in the head of a page
The link types that are taken out of a rel, since they'd speak for the page that shows the HTML: me, which says that the link goes to another profile of the page's owner, author, license, and the endpoints that a page names for Webmention, Pingback, IndieAuth, Micropub and Microsub.
The link types that are taken out of a rel, since they'd speak for the page that shows the HTML: me, which says that the link goes to another profile of the page's owner, author, license, and the endpoints that a page names for Webmention, Pingback, IndieAuth, Micropub and Microsub.
The elements that are removed with their content.
The elements that are removed with their content.
(elements x)(elements x opts)The elements of the HTML or Hiccup x, read by opts, at any depth and
in document order, without the content of templates, which a browser
keeps out of the page.
The elements of the HTML or Hiccup `x`, read by `opts`, at any depth and in document order, without the content of templates, which a browser keeps out of the page.
(head x)(head x opts)The elements in the head of the page x, read by opts: the children
of its head element, and those before the page's content, which a
browser puts in the head even when there's no head tag.
The elements in the head of the page `x`, read by `opts`: the children of its head element, and those before the page's content, which a browser puts in the head even when there's no head tag.
(hiccup x)(hiccup x opts)The HTML, plain text or Hiccup x as Hiccup that's safe to render, by
these keys of opts:
What :element-fn returns is sanitized again, so that it can't bring in what isn't allowed, unless :trusted-element-fn? is true. An element that it returns as it was given is kept.
Plain text becomes paragraphs with line breaks. Text is decoded, e.g. < is <, so use a renderer that escapes text. With :plain-text?, any string is read as plain text, e.g. a summary that can hold a <, and nothing in it is decoded.
The HTML, plain text or Hiccup `x` as Hiccup that's safe to render, by these keys of `opts`: - elements of :allowed-tags are kept, with the attributes of :allowed-attributes, but without the :dropped-rels in a rel, e.g. the me that would let the writer of a comment sign in as the owner of the page - elements of :dropped-tags are removed with their content - other elements are replaced by their children - a URL is resolved against :base-url, if it's given, and kept as :url-fn rewrites it when its scheme is one of :allowed-schemes, so a relative URL is left out without a :base-url - an element that's kept, once its attributes and children are safe, is given to :element-fn, and replaced by the Hiccup that it returns, e.g. a p in place of an h1 What :element-fn returns is sanitized again, so that it can't bring in what isn't allowed, unless :trusted-element-fn? is true. An element that it returns as it was given is kept. Plain text becomes paragraphs with line breaks. Text is decoded, e.g. < is <, so use a renderer that escapes text. With :plain-text?, any string is read as plain text, e.g. a summary that can hold a <, and nothing in it is decoded.
Elements that end a line in text and Markdown.
Elements that end a line in text and Markdown.
The elements that link somewhere when they have an href.
The elements that link somewhere when they have an href.
(links x)(links x opts)The elements of the page x that link somewhere, in document order, by
opts, with each href resolved against the page's base URL, as base-url
gives it:
An element whose href doesn't resolve is left out, e.g. a relative one when the page has no base element and there's no :base-url.
(map (comp :href second)
(links "<link rel=webmention href=/mention>"
{:base-url "https://example.com/post" :rel "webmention"}))
;; => ("https://example.com/mention")
The elements of the page `x` that link somewhere, in document order, by
`opts`, with each href resolved against the page's base URL, as base-url
gives it:
- :link-tags are the elements that count
- :rel is a link type, to take only the elements whose rel has it
- :body? false takes only the elements in the head of the page
An element whose href doesn't resolve is left out, e.g. a relative one
when the page has no base element and there's no :base-url.
(map (comp :href second)
(links "<link rel=webmention href=/mention>"
{:base-url "https://example.com/post" :rel "webmention"}))
;; => ("https://example.com/mention")(markdown x)(markdown x opts)The HTML or Hiccup x as Markdown, by opts. Text is escaped where
Markdown would read it as markup, and a link or an image is its text
when its URL isn't allowed. Control characters are left out, but for
tabs and line breaks.
The HTML or Hiccup `x` as Markdown, by `opts`. Text is escaped where Markdown would read it as markup, and a link or an image is its text when its URL isn't allowed. Control characters are left out, but for tabs and line breaks.
(markup? s)Whether the text s is HTML rather than plain text: whether it holds a
comment or a whole tag.
Whether the text `s` is HTML rather than plain text: whether it holds a comment or a whole tag.
How deep elements nest at most. An element opened deeper is kept empty, and its content goes to its parent, so that no walk of the tree overflows the stack.
How deep elements nest at most. An element opened deeper is kept empty, and its content goes to its parent, so that no walk of the tree overflows the stack.
How deep quotes nest in Markdown at most. A deeper quote is a plain paragraph, so that no line starts with hundreds of >.
How deep quotes nest in Markdown at most. A deeper quote is a plain paragraph, so that no line starts with hundreds of >.
Elements set off by a blank line in text and Markdown.
Elements set off by a blank line in text and Markdown.
(parse x)(parse x opts)The HTML or Hiccup x, read by opts, as a sequence of Hiccup nodes:
text, and elements that each have an attribute map. Nothing is
sanitized, so for HTML to render, use hiccup or sanitize.
HTML is nested at most as deep as :max-depth. Unclosed elements close where a browser closes them, but formatting isn't carried on past a misnested end tag. The html, head and body elements of a whole page stay as they're written. Comments and DOCTYPEs are left out.
Hiccup is read as every Hiccup renderer reads it, e.g. a tag such as :p.x is a p with a class. When :shorthand? is false, each tag is read as it's written, as it should be in the Hiccup that parse gives, e.g. the :x-a.b of <x-a.b>.
The HTML or Hiccup `x`, read by `opts`, as a sequence of Hiccup nodes: text, and elements that each have an attribute map. Nothing is sanitized, so for HTML to render, use hiccup or sanitize. HTML is nested at most as deep as :max-depth. Unclosed elements close where a browser closes them, but formatting isn't carried on past a misnested end tag. The html, head and body elements of a whole page stay as they're written. Comments and DOCTYPEs are left out. Hiccup is read as every Hiccup renderer reads it, e.g. a tag such as :p.x is a p with a class. When :shorthand? is false, each tag is read as it's written, as it should be in the Hiccup that parse gives, e.g. the :x-a.b of <x-a.b>.
(sanitize x)(sanitize x opts)The HTML, plain text or Hiccup x as HTML that's safe to render, by the
opts of hiccup.
The HTML, plain text or Hiccup `x` as HTML that's safe to render, by the `opts` of hiccup.
(serialize x)(serialize x opts)The HTML or Hiccup x, read by opts, as HTML that's written as a
browser writes it, by 13.3 of the HTML Standard. Nothing is sanitized,
so for HTML to render, use sanitize.
The HTML or Hiccup `x`, read by `opts`, as HTML that's written as a browser writes it, by 13.3 of the HTML Standard. Nothing is sanitized, so for HTML to render, use sanitize.
(text x)(text x opts)The HTML or Hiccup x as plain text, by opts. An image is its alt
text, and a link is followed by its URL when :links? and the URL is
allowed. Control characters are left out, but for tabs and line breaks.
The HTML or Hiccup `x` as plain text, by `opts`. An image is its alt text, and a link is followed by its URL when :links? and the URL is allowed. Control characters are left out, but for tabs and line breaks.
The attributes whose value is a URL.
The attributes whose value is a URL.
The attributes whose value is a list of URLs, separated by spaces, or by commas in a srcset.
The attributes whose value is a list of URLs, separated by spaces, or by commas in a srcset.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |