% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/generate-kb-xml.R
\name{generate_kb_xml}
\alias{generate_kb_xml}
\title{Generate a KB-importable XML file from a Quarto document}
\usage{
generate_kb_xml(html_path, qmd_path = NULL, output_dir = NULL)
}
\arguments{
\item{html_path}{A string. Path to the rendered HTML file. Used to infer
the output filename and, if \code{qmd_path} is \code{NULL}, the location of the
source \code{.qmd}.}

\item{qmd_path}{A string or \code{NULL}. Path to the source \code{.qmd} file. If
\code{NULL} (the default), inferred by replacing the \code{.html} extension of
\code{html_path} with \code{.qmd}.}

\item{output_dir}{A string or \code{NULL}. Directory where the \code{.xml} file
will be written. If \code{NULL} (the default), written to the same directory
as \code{html_path}.}
}
\value{
Invisibly returns the path to the written \code{.xml} file.
}
\description{
Takes a Quarto document and produces an XML file that is directly
importable into a UW-Madison Knowledge Base (KB) article. The function
re-renders the \code{.qmd} with \code{embed-resources: true} so all visual assets
are self-contained, extracts the HTML body, and wraps it in the KB XML
structure along with metadata drawn from the document's YAML header.
}
\details{
\code{generate_kb_xml()} performs the following steps:
\enumerate{
\item Validates that \code{html_path} exists.
\item Infers \code{qmd_path} from \code{html_path} if not supplied, then validates it.
\item Extracts \code{title}, \code{description}, and \code{categories} from the \code{.qmd} YAML
header and maps them to \code{kb_title}, \code{kb_summary}, and \code{kb_keywords}.
\item Re-renders the \code{.qmd} in an isolated temporary directory with
\code{embed-resources: true} so all CSS, images, and JS are self-contained.
The \verb{data/} and \verb{assets/} folders are copied alongside the \code{.qmd} to
ensure the render succeeds.
\item Extracts the \verb{<body>} from the embedded HTML.
\item Escapes HTML entities in the body for XML compatibility, as required
by the UW-Madison KB import format.
\item Builds the XML structure with \code{kb_title}, \code{kb_keywords}, \code{kb_summary},
and \code{kb_body} nodes.
\item Writes the \code{.xml} file to \code{output_dir}.
}

Temporary files are managed via \code{withr::local_tempdir()} and are
automatically cleaned up when the function exits, even on error.

When importing the resulting XML into the KB, check the
\emph{Decode HTML entity in body content} option.
}
\examples{
\donttest{
# Infer qmd_path automatically, write XML alongside the HTML
# generate_kb_xml(html_path = "docs/analysis.html")

# Supply qmd_path explicitly and write to a specific output directory
# generate_kb_xml(
#   html_path  = "docs/analysis.html",
#   qmd_path   = "analysis.qmd",
#   output_dir = "exports"
# )
}
}
