presentation-sanity 0.4.3__py3-none-any.whl

presentation_sanity/__init__.py

@@ -0,0 +1,3 @@
+"""presentation-sanity: build slides and blogs from a single manifest."""
+
+__version__ = "0.4.3"

presentation_sanity/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m presentation_sanity` — the same CLI, for environments without the script."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

presentation_sanity/assets/vitepress/citations.css

@@ -0,0 +1,89 @@
+/* GENERATED by presentation-sanity — DO NOT EDIT.
+ * Defaults for \cite{} labels and the \bibliography list. The subject's own
+ * blog.css is imported after this file, so anything here can be overridden
+ * there without touching the generated theme. */
+
+/* ─── In-text citations ──────────────────────────────────────────────────── */
+.vp-doc a.cite {
+  font-variant-numeric: tabular-nums;
+  text-decoration: none;
+  font-weight: 500;
+  white-space: nowrap;
+}
+.vp-doc a.cite:hover {
+  text-decoration: underline;
+}
+.cite--missing {
+  background: rgba(255, 80, 80, 0.16);
+  color: #c00;
+  border-radius: 2px;
+  padding: 0 0.2em;
+}
+
+/* ─── Reference list ─────────────────────────────────────────────────────── */
+.psanity-bibliography {
+  margin-top: 3.5rem;
+  border-top: 1px solid var(--vp-c-divider);
+  padding-top: 0.5rem;
+}
+.vp-doc .psanity-bibliography > :first-child {
+  margin-top: 1.2rem;
+}
+.vp-doc .psanity-bibliography ol.ref-list {
+  list-style: none;
+  padding-left: 0;
+  margin: 0;
+}
+
+/*
+ * Hanging indent: the marker sits in the gutter and continuation lines align
+ * under the reference text rather than under the marker.
+ *
+ * Inline flow is deliberate. `display: flex` or `grid` here looks like the
+ * obvious way to put the number beside the text, but a reference is a run of
+ * inline nodes — <em>journal</em>, <strong>volume</strong>, bare text, the DOI
+ * link — and each one becomes its own flex/grid item, so the entry renders as
+ * a row of narrow columns instead of a paragraph.
+ */
+.vp-doc .psanity-bibliography li.ref {
+  padding-left: 2.5em;
+  text-indent: -2.5em;
+  margin: 0.55rem 0;
+  font-size: 0.9em;
+  line-height: 1.65;
+  color: var(--vp-c-text-2);
+  /* Jumping from a citation shouldn't tuck the entry under the navbar. */
+  scroll-margin-top: 6rem;
+}
+.vp-doc .psanity-bibliography li.ref + li.ref {
+  margin-top: 0.55rem;
+}
+.vp-doc .psanity-bibliography .ref-number {
+  display: inline-block;
+  width: 2.5em;          /* matches the indent, so text lines up exactly */
+  text-indent: 0;        /* don't inherit the negative indent */
+  font-variant-numeric: tabular-nums;
+  color: var(--vp-c-text-3);
+}
+.vp-doc .psanity-bibliography li.ref em {
+  color: var(--vp-c-text-1);
+}
+.vp-doc .psanity-bibliography a {
+  text-decoration: none;
+  font-weight: 400;
+}
+.vp-doc .psanity-bibliography a:hover {
+  text-decoration: underline;
+}
+.vp-doc .psanity-bibliography a.ref-link {
+  font-size: 0.95em;
+  overflow-wrap: anywhere;   /* long DOIs shouldn't overflow the column */
+}
+
+/* Briefly mark the entry you jumped to. box-shadow rather than padding, so
+ * highlighting doesn't shift the hanging indent. */
+.vp-doc .psanity-bibliography li.ref:target {
+  background: var(--vp-c-default-soft);
+  border-radius: 3px;
+  box-shadow: 0 0 0 0.45rem var(--vp-c-default-soft);
+}

presentation_sanity/assets/vitepress/config.mts

@@ -0,0 +1,277 @@
+// GENERATED by presentation-sanity — DO NOT EDIT.
+// Rewritten from manifest.yaml on every `presentation-sanity build|dev`.
+// Change the blog's title, nav, base, math macros, etc. under `outputs.<key>:`
+// and `math:` in manifest.yaml. To take full ownership instead, copy this
+// directory elsewhere and point VitePress at it yourself.
+import { defineConfig } from 'vitepress'
+__IMPORTS__
+
+// Everything derivable from manifest.yaml, injected as a literal.
+const generated = __CONFIG_JSON__
+
+// ─── Bare LaTeX display environments ────────────────────────────────────────
+// markdown-it-mathjax3 only recognises `$…$` and `$$…$$`, so a document that
+// opens with `\begin{align}` — the way you'd write it in a .tex file — falls
+// through to the paragraph rule and renders as literal text with its `\\`
+// row breaks eaten. This block rule consumes `\begin{env}…\end{env}` and emits
+// the plugin's own `math_block` token, so such a block renders exactly as if
+// it had been fenced in `$$`.
+//
+// Names from `math.environments` in the manifest; starred variants match too.
+// In-math-only environments (matrix, cases, …) are deliberately absent — at
+// block level they would swallow the prose that follows.
+const MATH_ENVIRONMENTS: string[] = __ENVIRONMENTS__
+
+function installLatexEnvironments(md: any) {
+  if (!MATH_ENVIRONMENTS.length) return
+  const allowed = new Set(MATH_ENVIRONMENTS.map((e) => e.replace(/\*$/, '')))
+
+  function latexEnvironment(state: any, startLine: number, endLine: number, silent: boolean) {
+    // Four-space indent is a code block, not math.
+    if (state.sCount[startLine] - state.blkIndent >= 4) return false
+
+    const begin = state.bMarks[startLine] + state.tShift[startLine]
+    const opening = /^\\begin\{([A-Za-z]+\*?)\}/.exec(
+      state.src.slice(begin, state.eMarks[startLine]),
+    )
+    if (!opening) return false
+
+    const env = opening[1]
+    if (!allowed.has(env.replace(/\*$/, ''))) return false
+    if (silent) return true
+
+    // Scan for the matching \end{env}, counting nested opens of the same
+    // environment so `align` inside `align` closes at the right line.
+    const closing = `\\end{${env}}`
+    const reopen = `\\begin{${env}}`
+    let depth = 0
+    let line = startLine
+    let found = false
+    for (; line < endLine; line++) {
+      const text = state.src.slice(
+        state.bMarks[line] + state.tShift[line],
+        state.eMarks[line],
+      )
+      if (line > startLine && text.includes(reopen)) depth++
+      if (text.includes(closing)) {
+        if (depth === 0) { found = true; break }
+        depth--
+      }
+    }
+    // Unterminated: leave it to the paragraph rule rather than eating the
+    // rest of the document.
+    if (!found) return false
+
+    const token = state.push('math_block', 'math', 0)
+    token.block = true
+    token.content = state.getLines(startLine, line + 1, state.blkIndent, false)
+    token.map = [startLine, line + 1]
+    token.markup = '$$'
+    state.line = line + 1
+    return true
+  }
+
+  md.block.ruler.before('paragraph', 'latex_environment', latexEnvironment, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list'],
+  })
+}
+
+// ─── Citations ──────────────────────────────────────────────────────────────
+// LaTeX-shaped citing without a LaTeX toolchain. `\cite{key}` becomes a linked
+// label, `\bibliography` renders the reference list. Entries were parsed and
+// formatted from the manifest's .bib sources at scaffold time and injected
+// below, so nothing about citations reaches the browser — the page ships plain
+// anchors, the same bargain the math rendering makes.
+type BibEntry = {
+  html: string
+  text: string
+  label: string
+  labelBare: string
+  year: string
+  sortAuthor: string
+  sortYear: string
+}
+type BibData = {
+  style: 'numeric' | 'author-year'
+  sort: 'appearance' | 'author' | 'year'
+  title: string
+  heading: string
+  entries: Record<string, BibEntry>
+}
+
+const BIBLIOGRAPHY: BibData | null = __BIBLIOGRAPHY__
+
+const CITE_COMMANDS: Record<string, 'p' | 't' | 'no'> = {
+  cite: 'p',
+  citep: 'p',
+  citealp: 'p',
+  citet: 't',
+  citealt: 't',
+  nocite: 'no',
+}
+
+function escapeHtml(s: string) {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+function installCitations(md: any) {
+  const bib = BIBLIOGRAPHY
+  if (!bib) return
+  const warned = new Set<string>()
+
+  // \cite{a,b} · \citep[p. 12]{a} · \citet{a} · \nocite{a}
+  function citeRule(state: any, silent: boolean) {
+    if (state.src.charCodeAt(state.pos) !== 0x5c /* \ */) return false
+    const re = /^\\(cite|citep|citealp|citet|citealt|nocite)\s*(?:\[([^\]]*)\])?\{([^}]*)\}/
+    const m = re.exec(state.src.slice(state.pos))
+    if (!m) return false
+    const keys = m[3].split(',').map((k: string) => k.trim()).filter(Boolean)
+    if (!keys.length) return false
+    if (!silent) {
+      const token = state.push('psanity_cite', '', 0)
+      token.meta = { keys, form: CITE_COMMANDS[m[1]], note: (m[2] || '').trim() }
+    }
+    state.pos += m[0].length
+    return true
+  }
+
+  // A line that is only \bibliography, \bibliography{...} or \printbibliography
+  function bibliographyRule(state: any, startLine: number, _end: number, silent: boolean) {
+    if (state.sCount[startLine] - state.blkIndent >= 4) return false
+    const line = state.src
+      .slice(state.bMarks[startLine] + state.tShift[startLine], state.eMarks[startLine])
+      .trim()
+    if (!/^\\(?:print)?bibliography(\{[^}]*\})?$/.test(line)) return false
+    if (silent) return true
+    state.push('psanity_bibliography', '', 0)
+    state.line = startLine + 1
+    return true
+  }
+
+  // Collect every cited key, then fix numbering and list order in one pass —
+  // so `sort: author` can still produce ascending [1],[2] in the text.
+  function collectRule(state: any) {
+    const seen: string[] = []
+    const visit = (tokens: any[]) => {
+      for (const t of tokens) {
+        if (t.type === 'psanity_cite') {
+          for (const k of t.meta.keys) if (!seen.includes(k)) seen.push(k)
+        }
+        if (t.children) visit(t.children)
+      }
+    }
+    visit(state.tokens)
+
+    const known = seen.filter((k) => bib.entries[k])
+    let order = known.slice()
+    if (bib.sort === 'author') {
+      order.sort((a, b) => bib.entries[a].sortAuthor.localeCompare(bib.entries[b].sortAuthor))
+    } else if (bib.sort === 'year') {
+      order.sort((a, b) => bib.entries[a].sortYear.localeCompare(bib.entries[b].sortYear))
+    }
+    const numbers: Record<string, number> = {}
+    order.forEach((k, i) => { numbers[k] = i + 1 })
+    state.env.psanityBib = { order, numbers }
+  }
+
+  // BEFORE 'escape', not after: markdown-it's escape rule consumes `\X` for
+  // *any* X — including `\c` — and returns true, so a rule registered after it
+  // never sees `\cite`. Running first is safe because this rule only matches a
+  // backslash followed by a known citation command, so `\$100` and friends
+  // still fall through to escape, and `$…$` still reaches the math rule.
+  md.inline.ruler.before('escape', 'psanity_cite', citeRule)
+  md.block.ruler.before('paragraph', 'psanity_bibliography', bibliographyRule, {
+    alt: ['paragraph', 'reference', 'blockquote', 'list'],
+  })
+  md.core.ruler.push('psanity_collect_citations', collectRule)
+
+  md.renderer.rules.psanity_cite = (tokens: any[], idx: number, _o: any, env: any) => {
+    const { keys, form, note } = tokens[idx].meta
+    if (form === 'no') return ''
+    const numbers = env?.psanityBib?.numbers ?? {}
+    const parts = keys.map((key: string) => {
+      const entry = bib.entries[key]
+      if (!entry) {
+        if (!warned.has(key)) {
+          warned.add(key)
+          console.warn(`  warning: \\cite{${key}} — no such key in the bibliography`)
+        }
+        return `<span class="cite cite--missing">?${escapeHtml(key)}</span>`
+      }
+      const href = `#ref-${encodeURIComponent(key)}`
+      const title = escapeHtml(entry.text)
+      if (bib.style === 'author-year') {
+        const inner = form === 't' ? entry.labelBare : entry.label
+        return `<a class="cite" href="${href}" title="${title}">${escapeHtml(inner)}</a>`
+      }
+      return `<a class="cite" href="${href}" title="${title}">${numbers[key]}</a>`
+    })
+
+    // The locator comes straight from markdown, so apply the TeX dash
+    // conventions the .bib fields already get: `pp. 401--403` → 401–403.
+    const suffix = note
+      ? `, ${escapeHtml(note.replace(/---/g, '\u2014').replace(/--/g, '\u2013'))}`
+      : ''
+    if (bib.style === 'author-year') {
+      // \citet{k} → Smith et al. (2020); \citep{k} → (Smith et al., 2020)
+      if (form === 't' && keys.length === 1) {
+        const entry = bib.entries[keys[0]]
+        const year = entry ? escapeHtml(entry.year) : ''
+        return `${parts[0]} (${year}${suffix})`
+      }
+      return `(${parts.join('; ')}${suffix})`
+    }
+    const body = `[${parts.join(', ')}${suffix}]`
+    return form === 't' && keys.length === 1 && bib.entries[keys[0]]
+      ? `${escapeHtml(bib.entries[keys[0]].labelBare)} ${body}`
+      : body
+  }
+
+  md.renderer.rules.psanity_bibliography = (_t: any, _i: number, _o: any, env: any) => {
+    const order: string[] = env?.psanityBib?.order ?? []
+    if (!order.length) return ''
+    const numbered = bib.style === 'numeric'
+    const items = order
+      .map((key) => {
+        const e = bib.entries[key]
+        // No trailing space: .ref-number is a fixed-width inline-block, so the
+        // gap is the CSS width and the text aligns with the hanging indent.
+        const n = numbered ? `<span class="ref-number">[${env.psanityBib.numbers[key]}]</span>` : ''
+        return `<li class="ref" id="ref-${encodeURIComponent(key)}">${n}${e.html}</li>`
+      })
+      .join('\n')
+    const h = /^h[1-6]$/.test(bib.heading) ? bib.heading : 'h2'
+    const title = bib.title
+      ? `<${h} id="${encodeURIComponent(bib.title.toLowerCase().replace(/\s+/g, '-'))}">${escapeHtml(bib.title)}</${h}>`
+      : ''
+    return `<div class="psanity-bibliography">\n${title}\n<ol class="ref-list">\n${items}\n</ol>\n</div>\n`
+  }
+}
+
+export default defineConfig({
+  ...generated,
+  markdown: {
+    ...generated.markdown,
+    // Runs after VitePress installs markdown-it-mathjax3, so the `math_block`
+    // renderer the rule above emits into is already registered.
+    config: (md: any) => {
+      if (generated.markdown?.math) installLatexEnvironments(md)
+      installCitations(md)
+    },
+  },
+  vite: {
+    // `configFile: false` is load-bearing. The subject root also holds a
+    // `vite.config.ts` for Slidev, and VitePress would otherwise merge it in:
+    // its `base: './'` is invalid for VitePress routing, and its yaml plugin
+    // would transform manifest.yaml a SECOND time — the double pass re-parses
+    // the emitted JS as YAML and hands every component a string instead of the
+    // manifest. This config is self-contained; the deck's is left to the deck.
+    configFile: false,
+    plugins: [__VITE_PLUGINS__],
+    // In a project: `@project` → the project root, `@shared` → its shared/ Vue
+    // layer — the same aliases the deck's shared/vite.config.ts defines, so a
+    // component imports `@project/manifest.yaml` identically in both engines.
+    resolve: { alias: __ALIASES__ },
+  },
+})

presentation_sanity/assets/vitepress/theme.ts

@@ -0,0 +1,43 @@
+// GENERATED by presentation-sanity — DO NOT EDIT.
+//
+// Wires the shared Vue components into VitePress so the same components back
+// both the Slidev deck and the blog:
+//
+//   * every component file is registered globally under its filename, which
+//     is exactly the convention Slidev already uses. `<DataValue>`,
+//     `<ManimFigure>`, `<FigureImage>` therefore work in markdown with no
+//     per-file imports.
+//   * `ProvenancePanel` is mounted once in the `layout-bottom` slot — the
+//     VitePress equivalent of Slidev's `global-bottom.vue` singleton.
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+__THEME_IMPORTS__
+
+// Literal globs (Vite requires static patterns), in priority order: a later
+// directory overrides an earlier one, so a presentation's own component wins
+// over the shared component of the same name.
+const sources = [
+__COMPONENT_GLOBS__
+]
+
+const components: Record<string, any> = {}
+for (const modules of sources) {
+  for (const [path, mod] of Object.entries(modules)) {
+    const name = path.split('/').pop()!.replace(/\.vue$/, '')
+    if (mod?.default) components[name] = mod.default
+  }
+}
+
+export default {
+  extends: DefaultTheme,
+  Layout() {
+    const panel = components.ProvenancePanel
+    return h(DefaultTheme.Layout, null, panel ? { 'layout-bottom': () => h(panel) } : {})
+  },
+  enhanceApp({ app }) {
+    for (const [name, component] of Object.entries(components)) {
+      app.component(name, component)
+    }
+  },
+} satisfies Theme