Document library

2024-12-02 17:27:42 +01:00 · 2024-12-02 17:27:42 +01:00 · cfd83df713
commit cfd83df713
parent cb2a6da25c
4 changed files with 325 additions and 27 deletions
--- a/src/lib.rs
+++ b/src/lib.rs
@ -1,7 +1,71 @@
-//! Create HTML by manipulating elements as structured data. Inspired by the
-//! clojure library [hiccup][hiccup].
+//! # el
+//!
+//! Write, modify, and safely render HTML elements as simple data structures.
+//!
+//! This library is inspired by [hiccup] and named after a small helper function
+//! I once wrote in JS.
 //!
 //! [hiccup]: https://github.com/weavejester/hiccup
+//!
+//! ## Library overview
+//!
+//! The basic data structure is the [`Element`], which can be rendered to a
+//! [`String`] using the [`Render`] trait. Custom elements can be constructed
+//! using [`Element::normal`] or [`Element::new`]. Once constructed, elements
+//! can be modified by accessing their fields or using the [`Element::add`] or
+//! [`Element::with`] methods, though this is usually not necessary.
+//!
+//! Constructor functions for all (non-deprecated) HTML tags can be found in the
+//! [`html`] module, SVG tags in [`svg`] and MathML tags in [`mathml`]. These
+//! three modules are designed to be wildcard-included for more concise code,
+//! either on a per-function or per-file basis.
+//!
+//! Element construction uses the [`ElementComponent`] trait, which represents
+//! not only element contents but also attributes. Tuples, arrays, [`Vec`],
+//! [`Option`], and [`Result`] can be used to combine components. The order of
+//! content components is preserved. To set attributes, include [`Attr`] values
+//! as components.
+//!
+//! If you want to render an entire web page, wrap an [`html::html`] element in
+//! a [`Document`]. When rendered, documents include the `<!DOCTYPE html>`
+//! annotation required by the standard.
+//!
+//! ## Usage example
+//!
+//! ```
+//! use el::{Attr, Render, html::*};
+//!
+//! let page: String = html((
+//!     head((
+//!         meta(Attr::new("charset", "utf-8")),
+//!         meta((
+//!             Attr::new("name", "viewport"),
+//!             Attr::new("content", "width=device-width, initial-scale=1"),
+//!         )),
+//!         title("Example page"),
+//!     )),
+//!     body((
+//!         h1((Attr::id("heading"), "Example page")),
+//!         p(("This is an example for a ", em("simple"), " web page.")),
+//!     )),
+//! ))
+//! .render_to_string()
+//! .unwrap();
+//! ```
+//!
+//! ## Axum support
+//!
+//! The [axum] crate is supported via the optional `axum` feature flag. When it
+//! is enabled, [`Document`] implements axum's `IntoResponse` trait and can be
+//! returned directly from handlers. In order to prevent accidentally returning
+//! incomplete HTML documents, [`Element`] does not implement `IntoResponse`.
+//!
+//! ```toml
+//! [dependencies]
+//! el = { version = "...", features = ["axum"] }
+//! ```
+//!
+//! [axum]: https://crates.io/crates/axum

 #[cfg(feature = "axum")]
 mod axum;