use std::sync::OnceLock;
use axum::extract::{Path, Query, State};
use axum::http::HeaderMap;
use axum::response::{IntoResponse, Redirect, Response};
use rustango::extractors::{SessionUser, Tenant};
use serde::Deserialize;
use serde_json::json;
use tera::Context;
use super::handlers::{add_admin_theme, add_chrome, render_with_csrf};
use super::AdminError;
include!(concat!(env!("OUT_DIR"), "/help_docs.rs"));
pub const DOCS_SITE: &str = "https://cms.rustango.com";
const REPO_DOCS: &str = "https://github.com/ujeenet/rustango-cms/blob/main/docs";
#[derive(Debug, Deserialize)]
pub(crate) struct SearchQuery {
#[serde(default)]
pub q: String,
}
struct Guide {
section: &'static str,
slug: &'static str,
title: String,
markdown: &'static str,
}
fn guides() -> &'static [Guide] {
static GUIDES: OnceLock<Vec<Guide>> = OnceLock::new();
GUIDES.get_or_init(|| {
HELP_SECTIONS
.iter()
.flat_map(|(section, _, pages)| {
pages.iter().map(move |(slug, markdown)| Guide {
section,
slug,
title: title_of(markdown, slug),
markdown,
})
})
.collect()
})
}
fn title_of(markdown: &str, slug: &str) -> String {
markdown
.lines()
.find_map(|l| l.strip_prefix("# "))
.map_or_else(|| slug.replace('-', " "), |t| t.trim().to_owned())
}
fn contents() -> serde_json::Value {
let mut sections = Vec::new();
for (title, slug, pages) in HELP_SECTIONS {
let items: Vec<_> = pages
.iter()
.filter_map(|(page, _)| guides().iter().find(|g| g.slug == *page))
.map(|g| json!({ "slug": g.slug, "title": g.title }))
.collect();
sections.push(json!({ "title": title, "slug": slug, "guides": items }));
}
serde_json::Value::Array(sections)
}
fn rewrite_links(markdown: &str) -> String {
static LINK: OnceLock<regex::Regex> = OnceLock::new();
static SRC: OnceLock<regex::Regex> = OnceLock::new();
let link = LINK.get_or_init(|| regex::Regex::new(r"\]\(([^)\s]+)\)").expect("valid regex"));
let src = SRC.get_or_init(|| regex::Regex::new(r#"src="img/"#).expect("valid regex"));
let out = link.replace_all(markdown, |c: ®ex::Captures<'_>| format!("]({})", target(&c[1])));
src.replace_all(&out, format!(r#"src="{DOCS_SITE}/static/img/"#)).into_owned()
}
fn target(href: &str) -> String {
if href.starts_with("http://")
|| href.starts_with("https://")
|| href.starts_with("mailto:")
|| href.starts_with('#')
|| href.starts_with('/')
{
return href.to_owned();
}
if let Some(rest) = href.strip_prefix("img/") {
return format!("{DOCS_SITE}/static/img/{rest}");
}
let (path, fragment) = href.split_once('#').map_or((href, ""), |(p, f)| (p, f));
if let Some(stem) = path.strip_suffix(".md") {
if !stem.contains('/') && guides().iter().any(|g| g.slug == stem) {
let frag = if fragment.is_empty() { String::new() } else { format!("#{fragment}") };
return format!("/cms-admin/help/{stem}{frag}");
}
}
format!("{REPO_DOCS}/{href}")
}
fn snippet(markdown: &str, needle: &str) -> String {
let flat: String = markdown
.lines()
.filter(|l| !l.trim_start().starts_with('#') && !l.trim_start().starts_with("```") && !l.contains("]("))
.collect::<Vec<_>>()
.join(" ")
.replace(['*', '`', '|', '>'], "");
let lower = flat.to_lowercase();
let Some(at) = lower.find(needle) else {
return flat.chars().take(160).collect();
};
let start = flat[..at].char_indices().rev().nth(70).map_or(0, |(i, _)| i);
let start = if start == 0 { 0 } else { flat[start..at].find(' ').map_or(start, |s| start + s + 1) };
let text: String = flat[start..].chars().take(180).collect();
format!("{}{}…", if start > 0 { "…" } else { "" }, text.trim())
}
pub(crate) async fn index(
State(state): State<super::AdminState>,
tenant: Tenant,
headers: HeaderMap,
SessionUser(user): SessionUser,
Query(q): Query<SearchQuery>,
) -> Result<Response, AdminError> {
if user.is_none() {
return Ok(Redirect::to("/login").into_response());
}
let mut ctx = Context::new();
add_chrome(&mut ctx, &tenant, "help", user.as_ref()).await;
add_admin_theme(&mut ctx, tenant.pool()).await;
ctx.insert("sections", &contents());
ctx.insert("docs_site", DOCS_SITE);
let query = q.q.trim().to_lowercase();
ctx.insert("q", q.q.trim());
if !query.is_empty() {
let results: Vec<_> = guides()
.iter()
.filter(|g| g.title.to_lowercase().contains(&query) || g.markdown.to_lowercase().contains(&query))
.map(|g| json!({ "slug": g.slug, "title": g.title, "section": g.section, "snippet": snippet(g.markdown, &query) }))
.collect();
ctx.insert("results", &results);
}
render_with_csrf(&state, &headers, "rcms_admin/help_index.html", &mut ctx)
}
pub(crate) async fn guide(
State(state): State<super::AdminState>,
tenant: Tenant,
headers: HeaderMap,
SessionUser(user): SessionUser,
Path(slug): Path<String>,
) -> Result<Response, AdminError> {
if user.is_none() {
return Ok(Redirect::to("/login").into_response());
}
let all = guides();
let Some(pos) = all.iter().position(|g| g.slug == slug) else {
return Ok(Redirect::to("/cms-admin/help").into_response());
};
let g = &all[pos];
let mut ctx = Context::new();
add_chrome(&mut ctx, &tenant, "help", user.as_ref()).await;
add_admin_theme(&mut ctx, tenant.pool()).await;
let body = g.markdown.split_once('\n').filter(|(first, _)| first.starts_with("# ")).map_or(g.markdown, |(_, rest)| rest);
ctx.insert("title", &g.title);
ctx.insert("section", g.section);
ctx.insert("body_html", &crate::markdown::render(&rewrite_links(body)));
ctx.insert("sections", &contents());
ctx.insert("current", g.slug);
ctx.insert("public_url", &format!("{DOCS_SITE}/{}", g.slug));
let neighbour = |i: Option<usize>| i.and_then(|i| all.get(i)).map(|n| json!({ "slug": n.slug, "title": n.title }));
ctx.insert("prev", &neighbour(pos.checked_sub(1)));
ctx.insert("next", &neighbour(pos.checked_add(1)));
render_with_csrf(&state, &headers, "rcms_admin/help_page.html", &mut ctx)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_listed_guide_is_bundled_with_a_title() {
assert!(guides().len() >= 10, "{} guides", guides().len());
for g in guides() {
assert!(!g.title.is_empty() && !g.markdown.is_empty(), "{}", g.slug);
}
assert!(guides().iter().any(|g| g.slug == "themes"), "the themes guide is listed");
}
#[test]
fn links_point_where_they_work_from_the_admin() {
assert_eq!(target("themes.md"), "/cms-admin/help/themes");
assert_eq!(target("themes.md#theme-packages"), "/cms-admin/help/themes#theme-packages");
assert_eq!(target("img/admin-ui/x.png"), format!("{DOCS_SITE}/static/img/admin-ui/x.png"));
assert_eq!(target("../examples/cms_demo"), format!("{REPO_DOCS}/../examples/cms_demo"));
assert_eq!(target("https://example.com"), "https://example.com");
assert_eq!(target("#section"), "#section");
assert!(rewrite_links(" and [t](themes.md)").contains("/cms-admin/help/themes"));
}
#[test]
fn a_snippet_shows_the_match_in_context() {
let s = snippet("# T\n\nSome text before the **theme package** and after.", "theme package");
assert!(s.contains("theme package"), "{s}");
assert!(!s.contains("**"), "{s}");
let long = format!("{} the theme package here", "word ".repeat(40));
let s = snippet(&long, "theme package");
assert!(s.starts_with("…word"), "starts at a word: {s}");
}
}