askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
docs_detail.py · 10.3 KB · 239 lines
| 1 | """One guide page, GET /docs/{slug}. |
| 2 | |
| 3 | The `slug` route-capture param comes from the site_routes pattern |
| 4 | `/docs/{slug}` (see seed/site_routes.tsv): captured params are merged into |
| 5 | the object's request payload under their capture-group name, the same way |
| 6 | `/articles/{article_id}` hands site_view_render `request["article_id"]` |
| 7 | (see object_site_routes.py / site-routing.md) -- so this object reads |
| 8 | `request["slug"]`. |
| 9 | |
| 10 | The record lookup happens client-side against the same cached manifest the |
| 11 | sidebar renders from (window.dbbasicDocsNav, /docs-nav) rather than a |
| 12 | second server round trip: the manifest is already being fetched to build |
| 13 | the sidebar on every /docs* page load, so a per-record fetch here would be |
| 14 | pure duplication for records that are, at most, a few hundred KB combined. |
| 15 | |
| 16 | Body markdown renders through the ONE shared renderer at /markdown |
| 17 | (window.dbbasicMarkdown) -- never a second implementation -- into a |
| 18 | `.markdownblock` container, which is the same class /style already themes |
| 19 | for read-only textarea content (see app-theme/style.py). |
| 20 | |
| 21 | Page-unique layout only; palette, chrome, and inputs come from /style. The |
| 22 | sidebar/off-canvas CSS below is intentionally identical to docs_index.py's |
| 23 | -- see that file's docstring for why it is duplicated rather than shared |
| 24 | through a second styling channel. |
| 25 | """ |
| 26 | |
| 27 | _STYLE = """ |
| 28 | .docslayout { display: flex; align-items: flex-start; gap: 0; max-width: 1180px; margin: 0 auto; } |
| 29 | .navtoggle { display: none; } |
| 30 | .scrim { display: none; } |
| 31 | |
| 32 | .docsidebar { width: 260px; flex: none; box-sizing: border-box; padding: 1rem 1.25rem 1rem 0; |
| 33 | position: sticky; top: 0; align-self: flex-start; max-height: 100vh; overflow-y: auto; } |
| 34 | .docsbrand { display: flex; align-items: center; gap: 0.5rem; font-weight: 700; color: var(--text); |
| 35 | margin-bottom: 1rem; } |
| 36 | .docsbrand:hover { text-decoration: none; color: var(--accent-strong); } |
| 37 | .docslogo { background: var(--accent); color: var(--accent-ink); border-radius: var(--radius-sm); |
| 38 | padding: 0.05rem 0.4rem; font-size: 0.78rem; font-weight: 700; } |
| 39 | #docsearch { margin-bottom: 0.75rem; } |
| 40 | .navempty { color: var(--muted); font-size: 0.85rem; } |
| 41 | .navheading { color: var(--muted); font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.03em; |
| 42 | margin: 1rem 0 0.3rem; } |
| 43 | .navgroup:first-child .navheading { margin-top: 0; } |
| 44 | .navlist { list-style: none; margin: 0; padding: 0; } |
| 45 | .navitem a { display: block; padding: 0.3rem 0.5rem; border-radius: var(--radius-sm); color: var(--text); |
| 46 | font-size: 0.88rem; } |
| 47 | .navitem a:hover { background: var(--panel-2); text-decoration: none; } |
| 48 | .navitem.active a { background: var(--accent); color: var(--accent-ink); font-weight: 600; } |
| 49 | |
| 50 | .docsmain { flex: 1; min-width: 0; padding: 1.5rem 1rem 3rem 2rem; border-left: 1px solid var(--line); } |
| 51 | .docsmain h1 { margin-top: 0; } |
| 52 | .docscontent { display: flex; align-items: flex-start; gap: 2rem; } |
| 53 | .docbody { flex: 1; min-width: 0; } |
| 54 | .doctoc { width: 200px; flex: none; padding-left: 1rem; border-left: 1px solid var(--line); |
| 55 | font-size: 0.82rem; position: sticky; top: 1rem; } |
| 56 | .doctochead { color: var(--muted); text-transform: uppercase; font-size: 0.72rem; margin-bottom: 0.4rem; } |
| 57 | .doctoclist { list-style: none; margin: 0; padding: 0; } |
| 58 | .doctocitem a { display: block; padding: 0.15rem 0; color: var(--muted); } |
| 59 | .doctocitem a:hover { color: var(--accent-strong); } |
| 60 | .doctocitem.doctocsub { padding-left: 0.75rem; } |
| 61 | |
| 62 | .docpager { display: flex; justify-content: space-between; gap: 1rem; margin-top: 2rem; |
| 63 | padding-top: 1rem; border-top: 1px solid var(--line); } |
| 64 | .docpagerside { flex: 1; display: flex; } |
| 65 | .docpagerlink { display: block; width: 100%; color: var(--text); border: 1px solid var(--line); |
| 66 | border-radius: var(--radius-md); padding: 0.6rem 0.8rem; font-size: 0.85rem; } |
| 67 | .docpagerlink:hover { border-color: var(--accent); text-decoration: none; } |
| 68 | .docpagerlink.next { text-align: right; } |
| 69 | |
| 70 | @media (max-width: 900px) { |
| 71 | .doctoc { display: none; } |
| 72 | } |
| 73 | |
| 74 | @media (max-width: 720px) { |
| 75 | .navtoggle { display: inline-flex; align-items: center; gap: 0.4rem; margin: 0.75rem 0 0 0.75rem; |
| 76 | background: var(--panel); border: 1px solid var(--line); color: var(--text); |
| 77 | border-radius: var(--radius-sm); padding: 0.4rem 0.7rem; font: inherit; cursor: pointer; } |
| 78 | .docslayout { display: block; } |
| 79 | .docsidebar { position: fixed; top: 0; left: 0; bottom: 0; width: 280px; max-width: 82vw; |
| 80 | background: var(--panel); border-right: 1px solid var(--line); padding: 1rem; |
| 81 | transform: translateX(-100%); transition: transform 160ms ease; z-index: 80; } |
| 82 | .docsidebar.open { transform: translateX(0); } |
| 83 | .scrim.open { display: block; position: fixed; inset: 0; background: rgba(0,0,0,0.45); z-index: 70; } |
| 84 | .docsmain { border-left: none; padding: 1rem; } |
| 85 | .docscontent { display: block; } |
| 86 | .doctoc { display: none; } |
| 87 | } |
| 88 | """ |
| 89 | |
| 90 | _BODY = """ |
| 91 | <button type="button" id="navtoggle" class="navtoggle" aria-label="Toggle documentation navigation" aria-expanded="false">☰ Menu</button> |
| 92 | <div id="scrim" class="scrim"></div> |
| 93 | <div class="docslayout"> |
| 94 | <aside id="sidebar" class="docsidebar"> |
| 95 | <div id="docsheader"></div> |
| 96 | <input id="docsearch" type="search" class="search" placeholder="Search docs…" aria-label="Search documentation"> |
| 97 | <div id="docsnav"><div class="navempty">Loading…</div></div> |
| 98 | </aside> |
| 99 | <main class="docsmain"> |
| 100 | <div class="docscontent"> |
| 101 | <div class="docbody" id="docmain"><div class="state">Loading…</div></div> |
| 102 | <aside class="doctoc" id="doctoc"></aside> |
| 103 | </div> |
| 104 | <div class="docpager" id="docpager"></div> |
| 105 | </main> |
| 106 | </div> |
| 107 | """ |
| 108 | |
| 109 | import re |
| 110 | |
| 111 | _SLUG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$") |
| 112 | |
| 113 | # `SLUG` is injected as a Python-repr'd JS string literal, same convention |
| 114 | # as view_render.py's VIEW_ID/RECORD_ID. |
| 115 | _SCRIPT = """ |
| 116 | (function () { |
| 117 | const esc = (s) => String(s == null ? "" : s).replace(/[&<>"']/g, |
| 118 | (c) => ({"&": "&", "<": "<", ">": ">", '"': """, "'": "'"}[c])); |
| 119 | |
| 120 | function slugify(text) { |
| 121 | const base = String(text == null ? "" : text).toLowerCase().trim() |
| 122 | .replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""); |
| 123 | return base || "section"; |
| 124 | } |
| 125 | |
| 126 | // Simple flat "on this page" list -- no scroll-spy, no nesting logic |
| 127 | // beyond a lighter indent for h3s. Gives every h2/h3 an id (from its |
| 128 | // text) if it doesn't already have one, deduping against ids already |
| 129 | // used on the page. |
| 130 | function buildToc(container) { |
| 131 | if (!container) return ""; |
| 132 | const heads = container.querySelectorAll("h2, h3"); |
| 133 | if (!heads.length) return ""; |
| 134 | const used = new Set(); |
| 135 | let html = '<div class="doctochead">On this page</div><ul class="doctoclist">'; |
| 136 | heads.forEach((heading) => { |
| 137 | if (!heading.id) { |
| 138 | const base = slugify(heading.textContent); |
| 139 | let id = base; |
| 140 | let n = 2; |
| 141 | while (used.has(id) || document.getElementById(id)) { id = base + "-" + n; n++; } |
| 142 | heading.id = id; |
| 143 | } |
| 144 | used.add(heading.id); |
| 145 | const subClass = heading.tagName === "H3" ? " doctocsub" : ""; |
| 146 | html += '<li class="doctocitem' + subClass + '"><a href="#' + esc(heading.id) + '">' |
| 147 | + esc(heading.textContent || "") + '</a></li>'; |
| 148 | }); |
| 149 | html += "</ul>"; |
| 150 | return html; |
| 151 | } |
| 152 | |
| 153 | function pagerHtml(prev, next) { |
| 154 | let html = '<div class="docpagerside">'; |
| 155 | if (prev) { |
| 156 | html += '<a class="docpagerlink prev" href="/docs/' + esc(prev.id) + '">← ' |
| 157 | + esc(prev.title || prev.id) + '</a>'; |
| 158 | } |
| 159 | html += '</div><div class="docpagerside">'; |
| 160 | if (next) { |
| 161 | html += '<a class="docpagerlink next" href="/docs/' + esc(next.id) + '">' |
| 162 | + esc(next.title || next.id) + ' →</a>'; |
| 163 | } |
| 164 | html += '</div>'; |
| 165 | return html; |
| 166 | } |
| 167 | |
| 168 | function renderNotFound() { |
| 169 | document.title = "Page not found — DBBASIC Docs"; |
| 170 | const main = document.getElementById("docmain"); |
| 171 | main.innerHTML = '<h1>Page not found</h1>' |
| 172 | + '<p>There is no guide at this address.</p>' |
| 173 | + '<p><a href="/docs">← Back to Docs</a></p>'; |
| 174 | document.getElementById("doctoc").innerHTML = ""; |
| 175 | document.getElementById("docpager").innerHTML = ""; |
| 176 | } |
| 177 | |
| 178 | async function init() { |
| 179 | if (!window.dbbasicDocsNav) return; |
| 180 | const records = await window.dbbasicDocsNav.mount({ |
| 181 | headerEl: document.getElementById("docsheader"), |
| 182 | navListEl: document.getElementById("docsnav"), |
| 183 | searchEl: document.getElementById("docsearch"), |
| 184 | drawerEl: document.getElementById("sidebar"), |
| 185 | toggleEl: document.getElementById("navtoggle"), |
| 186 | scrimEl: document.getElementById("scrim"), |
| 187 | activeSlug: SLUG, |
| 188 | }); |
| 189 | |
| 190 | const index = records.findIndex((r) => r && r.id === SLUG); |
| 191 | if (index === -1) { renderNotFound(); return; } |
| 192 | const record = records[index]; |
| 193 | |
| 194 | document.title = (record.title || SLUG) + " — DBBASIC Docs"; |
| 195 | const rendered = window.dbbasicMarkdown ? window.dbbasicMarkdown(record.content || "") : ""; |
| 196 | const main = document.getElementById("docmain"); |
| 197 | main.innerHTML = "<h1>" + esc(record.title || "") + '</h1><div class="markdownblock" id="docbodycontent">' |
| 198 | + rendered + "</div>"; |
| 199 | |
| 200 | document.getElementById("doctoc").innerHTML = buildToc(document.getElementById("docbodycontent")); |
| 201 | |
| 202 | const prev = index > 0 ? records[index - 1] : null; |
| 203 | const next = index < records.length - 1 ? records[index + 1] : null; |
| 204 | document.getElementById("docpager").innerHTML = pagerHtml(prev, next); |
| 205 | } |
| 206 | |
| 207 | init(); |
| 208 | })(); |
| 209 | """ |
| 210 | |
| 211 | |
| 212 | def GET(request): |
| 213 | slug = str(request.get("slug") or "").strip() |
| 214 | # Same defense as view_render.py's _RECORD_ID_RE gate: `slug` is |
| 215 | # URL-derived and lands inside a <script> block below, where string |
| 216 | # escaping alone cannot stop a "</script>" payload from closing the |
| 217 | # tag. Doc slugs are our own seed ids, so the tight charset costs |
| 218 | # nothing; anything else renders as the not-found state. |
| 219 | if not _SLUG_RE.fullmatch(slug): |
| 220 | slug = "" |
| 221 | _logger.info("site_docs_detail served", slug=slug or "missing") |
| 222 | |
| 223 | html = f"""<!doctype html> |
| 224 | <html lang="en"> |
| 225 | <head> |
| 226 | <meta charset="utf-8"> |
| 227 | <meta name="viewport" content="width=device-width, initial-scale=1"> |
| 228 | <title>DBBASIC Docs</title> |
| 229 | <link rel="stylesheet" href="/style"> |
| 230 | <style>{_STYLE}</style> |
| 231 | </head> |
| 232 | <body> |
| 233 | {_BODY} |
| 234 | <script src="/markdown"></script> |
| 235 | <script src="/docs-nav"></script> |
| 236 | <script>const SLUG = {slug!r};{_SCRIPT}</script> |
| 237 | </body> |
| 238 | </html>""" |
| 239 | return {"content_type": "text/html; charset=utf-8", "body": html} |