This crate allows HTML strings to be generated from within Rust code using the Builder pattern. Calls to add elements are repeatedly chained together to build up an HTML document. The struct is then flushed to a string which can be used elsewhere in your program.
The strings generated by this library are unformatted, but are not explicitly minimized. Whitespace passed into a string will generally be preserved. Note that escaping strings is also not automatic, although a function to do so is provided.
This crate is written in purely safe Rust with no production dependencies.
use build_html::{HtmlElement, HtmlTag, Html};
let element = HtmlElement::new(HtmlTag::Div)
.with_child(
HtmlElement::new(HtmlTag::ParagraphText)
.with_child("Paragraph Text".into())
.into()
)
.with_child(
HtmlElement::new(HtmlTag::PreformattedText)
.with_child("Preformatted Text".into())
.into()
)
.to_html_string();
assert_eq!(element, "<div><p>Paragraph Text</p><pre>Preformatted Text</pre></div>");The primary intention of this library is to provide an easy way to build dynamic elements that
can be injected into an HTML page or framework that is written in its own file. The advantage
to this is that it allows you to write the majority of your HTML with modern editor features
such as linting and syntax highlighting. You can use the standard library's include_str!
macro to "import" your html file and the format! macro to "inject" your new element.
However, if your page is very simple or the entire page is dynamic, you may want to create the
entire thing from within your Rust code. To meet this use case, the library provides the
HtmlPage struct. This struct implements the HtmlContainer interface, which can be used
to easily add body content.
use build_html::{HtmlPage, Html, HtmlContainer};
let page = HtmlPage::new()
.with_title("TITLE")
.with_paragraph("PARAGRAPH")
.to_html_string();
assert_eq!(page, concat!(
"<!DOCTYPE html><html>",
"<head><title>TITLE</title></head>",
"<body><p>PARAGRAPH</p></body>",
"</html>"
));use build_html::*;
let html: String = HtmlPage::new()
.with_title("My Page")
.with_header(1, "Main Content:")
.with_html(
HtmlElement::new(HtmlTag::Article)
.with_attribute("id", "article1")
.with_header_attr(2, "Hello, World", [("id", "article-head"), ("class", "header")])
.with_paragraph("This is a simple HTML demo")
)
.to_html_string();produces a string equivalent to:
<!DOCTYPE html>
<html>
<head>
<title>My Page</title>
</head>
<body>
<h1>Main Content:</h1>
<article id="article1">
<h2 id="article-head" class="header">Hello World</h2>
<p>This is a simple HTML demo</p>
</article>
</body>
</html>If you are trying to create a more complicated document, you may find it easier to create a
template from outside of Rust and build it into the binary with the include_str!() macro. Then,
you can generate the parts that need to be dynamically created with build_html and insert them
with the format!() macro.
If you have an idea for making this library better, feel free to open an issue or pull request on GitHub! I try to respond within a reasonable amount of time, but please keep in mind that maintaining this library is not my full time job.
This project was made possible thanks to the following great projects:
This project is licensed under the MIT license.
Copyright (C) 2020-2024 Joseph Skubal and Contributors