@lincyaw/render-notebook 1.0.0-rc.0 → 1.0.0-rc.2

package/README.md

@@ -2,7 +2,7 @@
 
 Presmium's notebook renderer: writes the IR as a Jupyter notebook (nbformat 4). Narration becomes Markdown cells, code in the kernel's language becomes code cells with their recorded outputs, and components show their fallback.
 
-Part of [Presmium](https://github.com/Lincyaw/presmium), which turns lectures written in MyST Markdown into web pages, slides, Jupyter notebooks and narrated lectures.
+Part of [Presmium](https://github.com/Lincyaw/presmium), which compiles canonical lecture.json teaching documents into web pages, slides, Jupyter notebooks and narrated playback.
 
 ## Install
 
@@ -12,11 +12,11 @@ pnpm add -D @lincyaw/cli @lincyaw/render-notebook
 
 ## Configuration
 
-In the headmatter, `renderers.notebook`: `kernel` (default `python3`) and `webUrl`, where components the notebook cannot show link to (by default `../web/` when the web pages are built too).
+In `lecture.json`, `metadata.renderers.notebook`: `kernel` (default `python3`) and `webUrl`, where components the notebook cannot show link to (by default `../web/` when the web pages are built too).
 
 ## Documentation
 
-- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/lecture.en.md)
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincyaw/render-notebook",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "Presmium's notebook renderer: writes the IR as a Jupyter notebook (nbformat 4)",
   "license": "Apache-2.0",
   "repository": {
@@ -35,8 +35,8 @@
     "vfile": "^5.3.7"
   },
   "peerDependencies": {
-    "@lincyaw/kernel": "^1.0.0-rc.0",
-    "@lincyaw/web": "^1.0.0-rc.0"
+    "@lincyaw/kernel": "^1.0.0-rc.2",
+    "@lincyaw/web": "^1.0.0-rc.2"
   },
   "peerDependenciesMeta": {
     "@lincyaw/web": {
@@ -44,8 +44,8 @@
     }
   },
   "devDependencies": {
-    "@lincyaw/cli": "1.0.0-rc.0",
-    "@lincyaw/kernel": "1.0.0-rc.0",
-    "@lincyaw/web": "1.0.0-rc.0"
+    "@lincyaw/cli": "1.0.0-rc.2",
+    "@lincyaw/kernel": "1.0.0-rc.2",
+    "@lincyaw/web": "1.0.0-rc.2"
   }
 }

package/src/domain/markdown.ts

@@ -9,7 +9,8 @@ export interface MarkdownText {
   degraded: string[]
 }
 
-export function toMarkdown(mdast: MdastNode, urls?: LowerOptions['urls']): MarkdownText {
+/** A Markdown tree as Markdown a notebook shows: MyST lowered to what Jupyter renders, then written block by block. */
+export function lowerToMarkdown(mdast: MdastNode, urls?: LowerOptions['urls']): MarkdownText {
   const lowered = lowerMyst(mdast, { urls, htmlUrls: true })
   const problems: string[] = []
   const parts = (lowered.mdast.children ?? []).map((block) => {

package/src/domain/messages.ts

@@ -0,0 +1,18 @@
+import type { Locale, MdastNode } from '@lincyaw/kernel'
+
+function text(value: string): MdastNode {
+  return { type: 'text', value }
+}
+
+export const NOTEBOOK_MESSAGES = {
+  'zh-CN': {
+    web: '网页版',
+    note: (name: MdastNode, web: MdastNode): MdastNode[] => [text('交互组件 '), name, text(' 需要在'), web, text('中查看。')],
+  },
+  'en': {
+    web: 'the web version',
+    note: (name: MdastNode, web: MdastNode): MdastNode[] => [text('The interactive component '), name, text(' can only be used in '), web, text('.')],
+  },
+} satisfies Record<Locale, unknown>
+
+export type NotebookMessages = (typeof NOTEBOOK_MESSAGES)[Locale]

package/src/domain/notebook.ts

@@ -1,4 +1,4 @@
-import { errorMessage, isRecord, languageId, withProp } from '@lincyaw/kernel'
+import { errorMessage, hasRendererExtension, isRecord, languageId, withPublishedAssets } from '@lincyaw/kernel'
 import type {
   CodeNode,
   ComponentNode,
@@ -9,20 +9,23 @@ import type {
   Locale,
   MdastNode,
   RecordedRun,
-  RendererExtension,
+  BoundRendererExtension,
   RunOutput,
   SourcePos,
   Support,
 } from '@lincyaw/kernel'
-import { toMarkdown } from './markdown.ts'
+import { lowerToMarkdown } from './markdown.ts'
+import { NOTEBOOK_MESSAGES } from './messages.ts'
+import type { NotebookMessages } from './messages.ts'
 
-export interface KernelSpec {
+/** The Jupyter kernel a notebook names (nbformat's `kernelspec`). */
+export interface JupyterKernelSpec {
   name: string
   display_name: string
   language: string
 }
 
-export const DEFAULT_KERNEL: KernelSpec = { name: 'python3', display_name: 'Python 3', language: 'python' }
+export const DEFAULT_JUPYTER_KERNEL: JupyterKernelSpec = { name: 'python3', display_name: 'Python 3', language: 'python' }
 
 export type NotebookCellInput = string | {
   cell_type: 'markdown' | 'code' | 'raw'
@@ -48,12 +51,12 @@ export interface NotebookCell {
 export interface Notebook {
   nbformat: 4
   nbformat_minor: 5
-  metadata: { kernelspec: KernelSpec, language_info: { name: string }, title?: string }
+  metadata: { kernelspec: JupyterKernelSpec, language_info: { name: string }, title?: string }
   cells: NotebookCell[]
 }
 
 export interface NotebookOptions {
-  kernel: KernelSpec
+  jupyterKernel: JupyterKernelSpec
   locale: Locale
   webLink?: (section: IRSection) => string | undefined
   extensionFor: (node: ComponentNode) => ComponentRenderer | undefined
@@ -70,47 +73,39 @@ export interface NotebookResult {
 
 type ComponentRenderer = (node: ComponentNode, block: IRBlock) => unknown
 
-const MESSAGES = {
-  'zh-CN': {
-    web: '网页版',
-    note: (name: MdastNode, web: MdastNode): MdastNode[] => [text('交互组件 '), name, text(' 需要在'), web, text('中查看。')],
-  },
-  'en': {
-    web: 'the web version',
-    note: (name: MdastNode, web: MdastNode): MdastNode[] => [text('The interactive component '), name, text(' can only be used in '), web, text('.')],
-  },
-} satisfies Record<Locale, unknown>
-
 function text(value: string): MdastNode {
   return { type: 'text', value }
 }
 
-export function support(node: IRNode, extensions: RendererExtension[]): Support {
-  return node.type === 'component' && !extensions.some(e => (!node.plugin || e.plugin === node.plugin) && e.components?.[node.name]) ? 'degraded' : 'full'
+/** How well a notebook shows a node: a component without a notebook extension is degraded. */
+const documentLayout = (node: IRNode): boolean => node.type === 'component' && node.plugin === 'presmium.layout' && ['PmColumns', 'PmStack', 'PmTabs'].includes(node.name)
+export function notebookSupport(node: IRNode, extensions: BoundRendererExtension[]): Support {
+  if (documentLayout(node)) return 'full'
+  return node.type === 'component' && !hasRendererExtension(node, extensions) ? 'degraded' : 'full'
 }
 
 export function renderNotebook(doc: IRDocument, options: NotebookOptions): NotebookResult {
-  const { kernel } = options
+  const { jupyterKernel } = options
   const out: NotebookResult = {
-    notebook: { nbformat: 4, nbformat_minor: 5, metadata: { kernelspec: kernel, language_info: { name: kernel.language } }, cells: [] },
+    notebook: { nbformat: 4, nbformat_minor: 5, metadata: { kernelspec: jupyterKernel, language_info: { name: jupyterKernel.language } }, cells: [] },
     skipped: [],
     problems: [],
     degraded: [],
     unlinked: 0,
   }
   if (doc.meta.title) out.notebook.metadata.title = doc.meta.title
-  const ids = new Set<string>()
+  const cellCounts = new Map<string, number>()
   const executions = { count: 0 }
-  for (const section of doc.sections) renderSection(section, options, out, ids, executions)
+  for (const section of doc.sections) renderSection(section, options, out, cellCounts, executions)
   return out
 }
 
-function renderSection(section: IRSection, options: NotebookOptions, out: NotebookResult, ids: Set<string>, executions: { count: number }): void {
+function renderSection(section: IRSection, options: NotebookOptions, out: NotebookResult, cellCounts: Map<string, number>, executions: { count: number }): void {
   let pending: { parts: string[], blocks: string[] } | undefined
 
   const cell = (type: NotebookCell['cell_type'], source: string | string[], blocks: string[], extra: Partial<NotebookCell> = {}) => {
     out.notebook.cells.push({
-      id: cellId(section, ids),
+      id: cellId(section, cellCounts),
       cell_type: type,
       ...extra,
       metadata: { ...extra.metadata, presmium: { section: section.id, blocks } },
@@ -123,7 +118,7 @@ function renderSection(section: IRSection, options: NotebookOptions, out: Notebo
   }
   const written = (mdast: MdastNode, block?: IRBlock): string => {
     const { media } = options
-    const { text, problems, degraded } = toMarkdown(mdast, media && block ? url => media(url, block.source) : undefined)
+    const { text, problems, degraded } = lowerToMarkdown(mdast, media && block ? url => media(url, block.source) : undefined)
     const where = { section: section.id, block: block?.id ?? 'title', source: block?.source ?? section.source }
     for (const problem of problems) out.problems.push({ message: `${where.section}#${where.block}: ${problem}`, source: where.source })
     if (degraded.length) out.degraded.push({ ...where, nodes: degraded })
@@ -141,7 +136,7 @@ function renderSection(section: IRSection, options: NotebookOptions, out: Notebo
     const shown = node.echo !== false
     const caption = codeCaption(node)
     if (caption && shown) markdown(caption, block)
-    if (languageId(node.lang) === languageId(options.kernel.language)) {
+    if (languageId(node.lang) === languageId(options.jupyterKernel.language)) {
       flush()
       const runs = node.outputs ?? []
       const count = runs.length ? ++executions.count : null
@@ -163,10 +158,19 @@ function renderSection(section: IRSection, options: NotebookOptions, out: Notebo
 
   const component = (original: ComponentNode, block: IRBlock) => {
     const node = published(original, block, options)
+    if (documentLayout(node)) {
+      if (typeof node.props.title === 'string' && node.props.title) markdown({ type: 'heading', depth: 3, children: [text(node.props.title)] }, block)
+      for (const [index, child] of (node.children ?? []).entries()) {
+        const title = node.name === 'PmTabs' && Array.isArray(node.props.tabTitles) ? node.props.tabTitles[index] : undefined
+        if (typeof title === 'string' && title) markdown({ type: 'heading', depth: 4, children: [text(title)] }, child)
+        renderBlock(child)
+      }
+      return
+    }
     const render = options.extensionFor(node)
     if (render) {
       try {
-        const cells = cellInputs(render(node, block))
+        const cells = toCellInputs(render(node, block))
         if (cells) {
           flush()
           for (const input of cells) {
@@ -190,7 +194,7 @@ function renderSection(section: IRSection, options: NotebookOptions, out: Notebo
     if (node.fallback) return markdown(node.fallback, block)
     const link = options.webLink?.(section)
     if (!link) out.unlinked++
-    markdown(webNote(node, MESSAGES[options.locale], link), block)
+    markdown(webNote(node, NOTEBOOK_MESSAGES[options.locale], link), block)
     const reason = render ? `the notebook extension of ${node.name} rendered nothing and it has no fallback` : `component ${node.name} has no notebook extension or fallback`
     out.skipped.push({ section: section.id, block: block.id, reason: `${reason}; a note points to the web version` })
     node.children?.forEach(renderBlock)
@@ -210,13 +214,11 @@ function renderSection(section: IRSection, options: NotebookOptions, out: Notebo
 
 function published(node: ComponentNode, block: IRBlock, options: NotebookOptions): ComponentNode {
   const { media } = options
-  if (!node.assets || !media) return node
-  let props = node.props
-  for (const [path, url] of Object.entries(node.assets)) props = withProp(props, path, media(url, block.source) ?? url)
-  return { ...node, props }
+  return media ? withPublishedAssets(node, url => media(url, block.source)) : node
 }
 
-function cellInputs(value: unknown): NotebookCellInput[] | undefined {
+/** The cells a notebook extension returned; throws when one is not a cell. */
+function toCellInputs(value: unknown): NotebookCellInput[] | undefined {
   if (value === undefined || value === null) return undefined
   const cells = Array.isArray(value) ? value : [value]
   for (const c of cells) {
@@ -240,7 +242,7 @@ function codeCaption(node: CodeNode): MdastNode | undefined {
   return children.length ? { type: 'paragraph', children } : undefined
 }
 
-function webNote(node: ComponentNode, t: (typeof MESSAGES)[Locale], url?: string): MdastNode {
+function webNote(node: ComponentNode, t: NotebookMessages, url?: string): MdastNode {
   const web = url ? { type: 'link', url, children: [text(t.web)] } : text(t.web)
   return { type: 'blockquote', children: [{ type: 'paragraph', children: t.note({ type: 'inlineCode', value: node.name }, web) }] }
 }
@@ -269,10 +271,9 @@ function lines(text: string): string[] {
   return text ? text.split(/(?<=\n)/) : []
 }
 
-function cellId(section: IRSection, ids: Set<string>): string {
+function cellId(section: IRSection, counts: Map<string, number>): string {
   const base = section.id.replace(/[^\w-]/g, '').slice(0, 48) || `section-${section.index}`
-  let n = 1
-  while (ids.has(`${base}-${n}`)) n++
-  ids.add(`${base}-${n}`)
+  const n = (counts.get(base) ?? 0) + 1
+  counts.set(base, n)
   return `${base}-${n}`
 }

package/src/node/presmium.ts

@@ -1,33 +1,34 @@
 import { createRequire } from 'node:module'
 import { writeFile } from 'node:fs/promises'
 import { basename, extname, join } from 'node:path'
-import { deckLocale } from '@lincyaw/kernel'
+import { deckLocale, WEB_RENDERER_PACKAGE } from '@lincyaw/kernel'
 import type { IRDocument, IRSection, PresmiumNodePlugin, RenderContext } from '@lincyaw/kernel'
-import { DEFAULT_KERNEL, renderNotebook, support } from '../domain/notebook.ts'
-import type { KernelSpec, NotebookOptions } from '../domain/notebook.ts'
+import { DEFAULT_JUPYTER_KERNEL, notebookSupport, renderNotebook } from '../domain/notebook.ts'
+import type { JupyterKernelSpec, NotebookOptions } from '../domain/notebook.ts'
 import { localMedia } from './media.ts'
 
 export type { NotebookCellInput } from '../domain/notebook.ts'
 
-const CHECK_ID = 'presmium.notebook'
+/** The notebook renderer's plugin ID, which is also the ID of the checks it reports. */
+const PLUGIN_ID = 'presmium.notebook'
 const { version } = createRequire(import.meta.url)('../../package.json') as { version: string }
 
 const plugin: PresmiumNodePlugin = {
-  id: CHECK_ID,
+  id: PLUGIN_ID,
   version,
   kernel: '^1.0.0',
   renderer: {
     id: 'notebook',
-    support,
+    support: notebookSupport,
     async build(doc, ctx) {
-      const { notebook, skipped, problems, degraded, unlinked } = renderNotebook(doc, { ...await options(doc, ctx), media: localMedia(ctx) })
-      for (const { message, source } of problems) ctx.report({ checkId: CHECK_ID, severity: 'warning', message, source: { file: source.file, line: source.line } })
+      const { notebook, skipped, problems, degraded, unlinked } = renderNotebook(doc, { ...await notebookOptions(doc, ctx), media: localMedia(ctx) })
+      for (const { message, source } of problems) ctx.report({ checkId: PLUGIN_ID, severity: 'warning', message, source: { file: source.file, line: source.line } })
       for (const { section, block, nodes, source } of degraded) {
         const message = `${section}#${block}: degraded in the notebook, which has no Jupyter form for ${nodes.join(', ')}; the text is kept`
-        ctx.report({ checkId: CHECK_ID, severity: 'warning', message, source: { file: source.file, line: source.line } })
+        ctx.report({ checkId: PLUGIN_ID, severity: 'warning', message, source: { file: source.file, line: source.line } })
       }
       if (unlinked > 0) {
-        ctx.report({ checkId: CHECK_ID, severity: 'info', message: `${unlinked} components the notebook cannot show are noted without a link to the web version; set renderers.notebook.webUrl to link them` })
+        ctx.report({ checkId: PLUGIN_ID, severity: 'info', message: `${unlinked} components the notebook cannot show are noted without a link to the web version; set renderers.notebook.webUrl to link them` })
       }
       const name = basename(doc.meta.entry, extname(doc.meta.entry)) || 'notebook'
       await writeFile(join(ctx.outDir, `${name}.ipynb`), `${JSON.stringify(notebook, null, 1)}\n`)
@@ -38,32 +39,31 @@ const plugin: PresmiumNodePlugin = {
 
 export default plugin
 
-async function options(doc: IRDocument, ctx: RenderContext): Promise<Omit<NotebookOptions, 'media'>> {
-  const warn = (message: string) => ctx.report({ checkId: CHECK_ID, severity: 'warning', message })
+async function notebookOptions(doc: IRDocument, ctx: RenderContext): Promise<Omit<NotebookOptions, 'media'>> {
+  const warn = (message: string) => ctx.report({ checkId: PLUGIN_ID, severity: 'warning', message })
   const { kernel, webUrl } = ctx.config
   if (webUrl !== undefined && typeof webUrl !== 'string') warn('renderers.notebook.webUrl must be a URL; components are not linked to the web version')
-  return { kernel: kernelSpec(kernel, warn), locale: deckLocale(ctx.lang), webLink: await webLink(doc, ctx, webUrl), extensionFor: ctx.extensionFor }
+  return { jupyterKernel: jupyterKernelSpec(kernel, warn), locale: deckLocale(ctx.lang), webLink: await webLink(doc, ctx, webUrl), extensionFor: ctx.extensionFor }
 }
 
-const WEB_PACKAGE = '@lincyaw/web'
-
 async function webLink(doc: IRDocument, ctx: RenderContext, webUrl: unknown): Promise<((section: IRSection) => string) | undefined> {
   if (typeof webUrl === 'string') return section => `${webUrl.replace(/#.*$/, '')}#${encodeURIComponent(section.id)}`
-  const web = doc.config.renderers.web?.package ?? WEB_PACKAGE
-  if (!ctx.renderers.includes('web') || web !== WEB_PACKAGE) return undefined
-  const layout = await import('@lincyaw/web/domain').catch(() => undefined)
-  if (!layout) return undefined
-  const links = layout.sectionLinks(layout.toPages(doc))
+  const web = doc.config.renderers.web?.package ?? WEB_RENDERER_PACKAGE
+  if (!ctx.renderers.includes('web') || web !== WEB_RENDERER_PACKAGE) return undefined
+  const webDomain = await import('@lincyaw/web/domain').catch(() => undefined)
+  if (!webDomain) return undefined
+  const links = webDomain.sectionLinks(webDomain.webPages(doc))
   return section => `../web${(links[section.id] ?? '/').replace(/^\/(?=#|$)/, '/index.html')}`
 }
 
-function kernelSpec(value: unknown, warn: (message: string) => void): KernelSpec {
-  if (value === undefined || value === DEFAULT_KERNEL.name) return DEFAULT_KERNEL
+/** The Jupyter kernel the configuration `renderers.notebook.kernel` names: a name, or `{ name, language, display_name }`. */
+function jupyterKernelSpec(value: unknown, warn: (message: string) => void): JupyterKernelSpec {
+  if (value === undefined || value === DEFAULT_JUPYTER_KERNEL.name) return DEFAULT_JUPYTER_KERNEL
   if (typeof value === 'string' && value) return { name: value, display_name: value, language: value.replace(/[-\d.]+$/, '') || value }
   if (typeof value === 'object' && value !== null && 'name' in value && 'language' in value && typeof value.name === 'string' && typeof value.language === 'string') {
     const displayName = 'display_name' in value && typeof value.display_name === 'string' ? value.display_name : value.name
     return { name: value.name, display_name: displayName, language: value.language }
   }
-  warn(`renderers.notebook.kernel must be a kernel name or { name, language, display_name }; using ${DEFAULT_KERNEL.name}`)
-  return DEFAULT_KERNEL
+  warn(`renderers.notebook.kernel must be a kernel name or { name, language, display_name }; using ${DEFAULT_JUPYTER_KERNEL.name}`)
+  return DEFAULT_JUPYTER_KERNEL
 }