start docs

ealmloff · ealmloff · commit 26d8a9bb4308 · 2026-05-05T15:00:55.000-05:00
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -23,4 +23,4 @@ jobs:
       no-default-features: true
       features: fullstack
       debug-symbols: false
-      dx-cli-version: 0.7.7
+      dx-cli-version: 0.7.6
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -54,4 +54,4 @@ jobs:
       features: fullstack
       debug-symbols: false
       base-path: ${{ github.event.repository.name }}
-      dx-cli-version: 0.7.7
+      dx-cli-version: 0.7.6
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
@@ -45,5 +45,5 @@ jobs:
       features: fullstack
       debug-symbols: false
       base-path: ${{ github.event.repository.name }}
-      dx-cli-version: 0.7.7
+      dx-cli-version: 0.7.6
       toolchain: nightly
diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml
@@ -21,4 +21,4 @@ jobs:
       no-default-features: true
       features: fullstack
       debug-symbols: false
-      dx-cli-version: 0.7.7
+      dx-cli-version: 0.7.6
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -16,6 +16,7 @@ version = "0.0.1"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/ealmloff/dioxus-code"
+homepage = "https://dioxuslabs.github.io/dioxus-code/"
 keywords = ["dioxus", "code", "highlighting", "editor"]
 categories = ["gui", "web-programming"]
 
@@ -30,8 +31,10 @@ edition.workspace = true
 license.workspace = true
 description = "Syntax-highlighted code blocks for Dioxus."
 repository.workspace = true
+homepage.workspace = true
 keywords.workspace = true
 categories.workspace = true
+readme = "README.md"
 
 [features]
 default = ["macro"]
diff --git a/build.rs b/build.rs
@@ -31,13 +31,14 @@ fn main() {
         fs::write(asset_dir.join(&css_file), css).unwrap();
 
         generated.push_str(&format!(
-            "    pub const {const_name}_CSS: Asset = asset!(\"/assets/generated/arborium-themes/{css_file}\");\n",
+            "    /// Stylesheet asset for the `{name}` theme.\n    pub const {const_name}_CSS: Asset = asset!(\"/assets/generated/arborium-themes/{css_file}\");\n",
             const_name = theme.const_name,
             css_file = css_file,
+            name = name,
         ));
 
         generated.push_str(&format!(
-            "    pub const {const_name}: Self = Self {{ name: \"{name}\", class: \"{class}\", asset: Self::{const_name}_CSS }};\n",
+            "    /// The `{name}` syntax theme.\n    pub const {const_name}: Self = Self {{ name: \"{name}\", class: \"{class}\", asset: Self::{const_name}_CSS }};\n",
             const_name = theme.const_name,
             name = name,
             class = class,
diff --git a/code-editor/Cargo.toml b/code-editor/Cargo.toml
@@ -5,8 +5,10 @@ edition.workspace = true
 license.workspace = true
 description = "Syntax-highlighted code editor component for Dioxus."
 repository.workspace = true
+homepage.workspace = true
 keywords.workspace = true
 categories.workspace = true
+readme = "../README.md"
 
 [dependencies]
 dioxus = { version = "0.7.0", default-features = false, features = ["lib"] }
diff --git a/code-editor/src/lib.rs b/code-editor/src/lib.rs
@@ -1,3 +1,6 @@
+#![doc = include_str!("../../README.md")]
+#![warn(missing_docs)]
+
 use dioxus::prelude::*;
 use dioxus_code::{CodeSpan, HighlightSpan, IntoTree, SourceCode, Theme};
 use std::{cell::RefCell, rc::Rc};
diff --git a/demo/Cargo.toml b/demo/Cargo.toml
@@ -10,13 +10,13 @@ categories.workspace = true
 publish = false
 
 [dependencies]
-dioxus = { version = "0.7.0" }
+dioxus = { version = "0.7.0", features = ["router"] }
 dioxus-code = { workspace = true, features = ["runtime", "lang-python", "lang-toml"] }
 dioxus-code-editor = { workspace = true }
 
 [features]
 default = ["desktop"]
 desktop = ["dioxus/desktop"]
 web = ["dioxus/web"]
-fullstack = ["dioxus/fullstack", "dioxus/cli-config"]
-server = ["dioxus/server", "dioxus/fullstack", "dioxus/cli-config"]
+fullstack = ["dioxus/fullstack"]
+server = ["dioxus/server", "dioxus/fullstack"]
diff --git a/demo/src/main.rs b/demo/src/main.rs
@@ -147,7 +147,7 @@ fn main() {
         let router = Router::new()
             .route(
                 "/api/static_routes",
-                post(|| async { Json(vec![base_route()]) }),
+                post(|| async { Json(static_routes()) }),
             )
             .serve_dioxus_application(cfg, App);
 
@@ -156,17 +156,28 @@ fn main() {
 }
 
 #[cfg(feature = "server")]
-fn base_route() -> String {
-    let base_path = dioxus::cli_config::base_path().unwrap_or_default();
+fn static_routes() -> Vec<String> {
+    Route::static_routes()
+        .iter()
+        .map(ToString::to_string)
+        .collect()
+}
 
-    match base_path.trim_matches('/') {
-        "" => "/".to_string(),
-        base_path => format!("/{base_path}/"),
+#[component]
+fn App() -> Element {
+    rsx! {
+        Router::<Route> {}
     }
 }
 
+#[derive(Routable, Clone, PartialEq)]
+enum Route {
+    #[route("/")]
+    Home {},
+}
+
 #[component]
-fn App() -> Element {
+fn Home() -> Element {
     let source = use_signal(|| STARTER.to_string());
     let active_theme = use_signal(|| 0usize);
     let scheme = use_signal(|| Scheme::System);
diff --git a/dioxus-code-macro/Cargo.toml b/dioxus-code-macro/Cargo.toml
@@ -5,8 +5,10 @@ edition.workspace = true
 license.workspace = true
 description = "Compile-time syntax highlighting macro for dioxus-code."
 repository.workspace = true
+homepage.workspace = true
 keywords.workspace = true
 categories.workspace = true
+readme = "../README.md"
 
 [lib]
 proc-macro = true
diff --git a/dioxus-code-macro/src/lib.rs b/dioxus-code-macro/src/lib.rs
@@ -1,3 +1,6 @@
+#![doc = include_str!("../../README.md")]
+#![warn(missing_docs)]
+
 use std::env;
 use std::fs;
 use std::path::{Path, PathBuf};
@@ -9,6 +12,13 @@ use quote::{format_ident, quote};
 use syn::parse::{Parse, ParseStream};
 use syn::{Expr, Ident, LitStr, Token, parse_macro_input};
 
+/// Compile-time syntax highlighting.
+///
+/// Reads a source file relative to the consumer's `CARGO_MANIFEST_DIR`, parses
+/// it with [`arborium`], and expands to the resulting span tree. Pass the path
+/// as a string literal, `concat!(...)`, or `env!(...)`. Optionally name the
+/// language explicitly with `code!("/path", "rust")`; otherwise it is inferred
+/// from the file extension.
 #[proc_macro]
 pub fn code(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as CodeInput);
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,3 +1,6 @@
+#![doc = include_str!("../README.md")]
+#![warn(missing_docs)]
+
 #[cfg(feature = "runtime")]
 use arborium::advanced::Span;
 #[cfg(feature = "runtime")]
@@ -11,6 +14,11 @@ const STYLE: Asset = asset!("/assets/dioxus-code.css");
 #[cfg(feature = "macro")]
 pub use dioxus_code_macro::code;
 
+/// A syntax-highlighting theme.
+///
+/// Themes are exposed as associated constants on `Theme` (for example
+/// [`Theme::TOKYO_NIGHT`]) and ship as scoped CSS so multiple themes can
+/// coexist on the same page without leaking styles.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Theme {
     name: &'static str,
@@ -19,14 +27,17 @@ pub struct Theme {
 }
 
 impl Theme {
+    /// The theme's canonical slug, e.g. `"tokyo-night"`.
     pub const fn name(self) -> &'static str {
         self.name
     }
 
+    /// The CSS class applied to the rendered code container, e.g. `"dxc-tokyo-night"`.
     pub const fn class(self) -> &'static str {
         self.class
     }
 
+    /// The Dioxus [`Asset`] for the theme's stylesheet.
     pub const fn asset(self) -> Asset {
         self.asset
     }
@@ -40,6 +51,11 @@ impl Default for Theme {
 
 include!(concat!(env!("OUT_DIR"), "/theme_assets.rs"));
 
+/// A parsed source string with its highlighted spans.
+///
+/// Produced by [`SourceCode::into_tree`] (runtime parsing) or by the
+/// [`code!`] macro (compile-time parsing). Pass it to [`Code`] for rendering,
+/// or inspect [`source`](Self::source) and [`spans`](Self::spans) directly.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CodeTree {
     source: String,
@@ -49,6 +65,9 @@ pub struct CodeTree {
 }
 
 impl CodeTree {
+    /// Build a tree from `'static` parts produced by the [`code!`] macro.
+    ///
+    /// You normally don't call this directly — the macro emits a call to it.
     pub fn from_static_parts(
         source: &'static str,
         language: &'static str,
@@ -62,6 +81,9 @@ impl CodeTree {
         }
     }
 
+    /// Build a tree with no highlighting and an error message describing why.
+    ///
+    /// Used as a fallback when language detection or parsing fails.
     pub fn plaintext(source: impl Into<String>, error: impl Into<String>) -> Self {
         Self {
             source: source.into(),
@@ -71,34 +93,49 @@ impl CodeTree {
         }
     }
 
+    /// The raw source text.
     pub fn source(&self) -> &str {
         &self.source
     }
 
+    /// The detected or explicitly set language slug, if any.
     pub fn language(&self) -> Option<&str> {
         self.language.as_deref()
     }
 
+    /// An error message, set when highlighting failed and the tree fell back to plaintext.
     pub fn error(&self) -> Option<&str> {
         self.error.as_deref()
     }
 
+    /// The highlight spans covering the source.
     pub fn spans(&self) -> &[HighlightSpan] {
         &self.spans
     }
 }
 
+/// A highlight span emitted by the [`code!`] macro at compile time.
+///
+/// Mirrors [`HighlightSpan`] but with a `'static` tag so it can live in a
+/// `const` array baked into the binary.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct StaticSpan {
+    /// Byte offset (inclusive) of the span's start in the source.
     pub start: u32,
+    /// Byte offset (exclusive) of the span's end in the source.
     pub end: u32,
+    /// Highlight tag class suffix (for example `"k"` for keywords).
     pub tag: &'static str,
 }
 
+/// A highlight span attached to a region of source text.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HighlightSpan {
+    /// Byte offset (inclusive) of the span's start in the source.
     pub start: u32,
+    /// Byte offset (exclusive) of the span's end in the source.
     pub end: u32,
+    /// Highlight tag class suffix (for example `"k"` for keywords).
     pub tag: &'static str,
 }
 
@@ -180,6 +217,11 @@ fn normalize_spans(spans: impl IntoIterator<Item = Span>) -> Vec<HighlightSpan>
     coalesced
 }
 
+/// Source text to highlight at runtime.
+///
+/// Available with the `runtime` feature. Build one with [`SourceCode::new`],
+/// optionally annotate it with a language or filename, then convert it via
+/// [`IntoTree::into_tree`] (or pass it directly to [`Code`]).
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SourceCode {
     source: String,
@@ -188,6 +230,7 @@ pub struct SourceCode {
 }
 
 impl SourceCode {
+    /// Wrap a raw source string with no language hint.
     pub fn new(source: impl Into<String>) -> Self {
         Self {
             source: source.into(),
@@ -196,11 +239,13 @@ impl SourceCode {
         }
     }
 
+    /// Set the language slug explicitly (for example `"rust"`).
     pub fn with_language(mut self, language: impl Into<String>) -> Self {
         self.language = Some(language.into());
         self
     }
 
+    /// Set a filename used to infer the language when none is set explicitly.
     pub fn with_name(mut self, name: impl Into<String>) -> Self {
         self.name = Some(name.into());
         self
@@ -243,7 +288,13 @@ impl SourceCode {
     }
 }
 
+/// Conversion into a [`CodeTree`] suitable for rendering.
+///
+/// Implemented for [`CodeTree`] (identity), [`SourceCode`] (highlights at
+/// runtime), and — with the `runtime` feature — `&str` and `String`
+/// (auto-detect the language and highlight).
 pub trait IntoTree {
+    /// Consume `self` and return its [`CodeTree`] representation.
     fn into_tree(self) -> CodeTree;
 }
 
@@ -299,6 +350,11 @@ impl From<String> for CodeSource {
     }
 }
 
+/// Pre-parsed source ready to hand to the [`Code`] component.
+///
+/// Anything implementing [`IntoTree`] — including [`CodeTree`], [`SourceCode`],
+/// and (with the `runtime` feature) string types — converts into this via the
+/// `#[props(into)]` field on [`CodeProps::src`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CodeSource(CodeTree);
 
