jupyter: improved output render and search

znai-docs/znai/release-notes/1.81/add-2025-10-19-jupyter-improved-render.md

@@ -0,0 +1,2 @@
+* Add: Jupyter notebooks improved search and llm.txt support
+* Add: Jupyter notebooks improved std output and tables cell rendering

znai-jupyter/src/main/java/org/testingisdocumenting/znai/jupyter/JupyterCell.java

@@ -43,4 +43,8 @@ public String getInput() {
     public List<JupyterOutput> getOutputs() {
         return outputs;
     }
+
+    public boolean hasTextOutput() {
+        return outputs.stream().anyMatch((output) -> output.format().equals(JupyterOutput.TEXT_FORMAT));
+    }
 }

znai-jupyter/src/main/java/org/testingisdocumenting/znai/jupyter/JupyterIncludePlugin.java

@@ -17,13 +17,9 @@
 
 package org.testingisdocumenting.znai.jupyter;
 
-import org.testingisdocumenting.znai.codesnippets.CodeSnippetsProps;
 import org.testingisdocumenting.znai.core.AuxiliaryFile;
 import org.testingisdocumenting.znai.core.ComponentsRegistry;
-import org.testingisdocumenting.znai.extensions.PluginParamType;
-import org.testingisdocumenting.znai.extensions.PluginParams;
-import org.testingisdocumenting.znai.extensions.PluginParamsDefinition;
-import org.testingisdocumenting.znai.extensions.PluginResult;
+import org.testingisdocumenting.znai.extensions.*;
 import org.testingisdocumenting.znai.extensions.include.IncludePlugin;
 import org.testingisdocumenting.znai.parser.ParserHandler;
 import org.testingisdocumenting.znai.parser.commonmark.MarkdownParser;
@@ -41,9 +37,9 @@ public class JupyterIncludePlugin implements IncludePlugin {
     private static final String EXCLUDE_SECTION_TITLE_KEY = "excludeSectionTitle";
     private MarkdownParser markdownParser;
     private Path path;
-    private String lang;
     private boolean isStoryFirst;
     private ParserHandler markdownParserHandler;
+    private PluginParamsFactory pluginParamsFactory;
 
     @Override
     public String id() {
@@ -69,6 +65,7 @@ public PluginParamsDefinition parameters() {
     public PluginResult process(ComponentsRegistry componentsRegistry, ParserHandler parserHandler, Path markupPath, PluginParams pluginParams) {
         markdownParser = componentsRegistry.markdownParser();
         markdownParserHandler = parserHandler;
+        pluginParamsFactory = componentsRegistry.pluginParamsFactory();
 
         isStoryFirst = pluginParams.getOpts().get(STORY_FIRST_KEY, false);
         List<String> includeSection = pluginParams.getOpts().getList(INCLUDE_SECTION_KEY);
@@ -79,7 +76,6 @@ public PluginResult process(ComponentsRegistry componentsRegistry, ParserHandler
 
         JupyterNotebook notebook = new JupyterParserVer4()
                 .parse(JsonUtils.deserializeAsMap(resourcesResolver.textContent(path)));
-        lang = notebook.getLang();
 
         List<JupyterCell> cells = !includeSection.isEmpty() ?
                 collectCells(notebook.getCells(), includeSection, excludeSectionTitle) :
@@ -109,6 +105,7 @@ private List<JupyterCell> collectCells(List<JupyterCell> cells, List<String> inc
 
     @Override
     public List<SearchText> textForSearch() {
+        // TODO extract output from html output cells as those are not being processed by markdown processor
         return List.of();
     }
 
@@ -137,15 +134,17 @@ private void processInputFromCell(JupyterCell cell) {
             return;
         }
 
-        Map<String, Object> props = new LinkedHashMap<>();
-        props.put("cellType", cell.getType());
-        props.putAll(convertInputData(cell));
-
-        if (isStoryFirst) {
-            props.putAll(createMetaRight());
+        Map<String, Object> props = isStoryFirst ? createRightSideProp() : new HashMap<>();
+        addJupyterCellClassName(props);
+        if (!cell.getOutputs().isEmpty()) {
+            props.put("noGap", true);
+            if (cell.hasTextOutput()) {
+                props.put("noGapBorder", true);
+            }
         }
 
-        addCell(props);
+        markdownParserHandler.onSnippet(pluginParamsFactory.create("snippet", "", props),
+                "python", "", cell.getInput());
     }
 
     private void processOutputFromCell(JupyterCell cell) {
@@ -157,15 +156,25 @@ private void processOutputFromCell(JupyterCell cell) {
     }
 
     private void processCellOutput(JupyterOutput output) {
-        Map<String, Object> props = new LinkedHashMap<>();
-        props.put("cellType", "output");
-        props.putAll(convertOutputData(output));
+        if (output.format().equals(JupyterOutput.TEXT_FORMAT)) {
+            Map<String, Object> props = !isStoryFirst ? createRightSideProp() : new HashMap<>();
+            props.put("resultOutput", true);
+            addJupyterCellClassName(props);
+
+            markdownParserHandler.
+                    onSnippet(pluginParamsFactory.create("snippet", "", props),
+                            "csv", "", output.content());
+        } else {
+            Map<String, Object> props = new LinkedHashMap<>();
+            props.put("cellType", "output");
+            props.putAll(convertOutputData(output));
 
-        if (!isStoryFirst) {
-            props.putAll(createMetaRight());
-        }
+            if (!isStoryFirst) {
+                props.putAll(createMetaRight());
+            }
 
-        addCell(props);
+            addCell(props);
+        }
     }
 
     private void processEmptyOutput() {
@@ -184,21 +193,22 @@ private boolean isMarkdown(JupyterCell cell) {
         return cell.getType().equals(JupyterCell.MARKDOWN_TYPE);
     }
 
-    private Map<String, ?> createMetaRight() {
-        Map<String, Object> meta = new LinkedHashMap<>();
-        meta.put("rightSide", true);
-
+    private Map<String, Object> createMetaRight() {
+        Map<String, Object> meta = createRightSideProp();
         return Collections.singletonMap("meta", meta);
     }
 
-    private Map<String, Object> convertInputData(JupyterCell cell) {
-        if (cell.getType().equals(JupyterCell.CODE_TYPE)) {
-            return CodeSnippetsProps.create(lang, cell.getInput());
-        }
-        return Collections.singletonMap(JupyterOutput.TEXT_FORMAT, cell.getInput());
+    private static Map<String, Object> createRightSideProp() {
+        Map<String, Object> meta = new LinkedHashMap<>();
+        meta.put("rightSide", true);
+        return meta;
     }
 
     private Map<String, Object> convertOutputData(JupyterOutput output) {
         return Collections.singletonMap(output.format(), output.content());
     }
+
+    private void addJupyterCellClassName(Map<String, Object> props) {
+        props.put("className", "znai-jupyter-cell");
+    }
 }

znai-jupyter/src/test/groovy/org/testingisdocumenting/znai/jupyter/JupyterIncludePluginTest.groovy

@@ -24,13 +24,13 @@ class JupyterIncludePluginTest {
     @Test
     void "should split each cell and create separate doc elements for each input and output"() {
         def elements = process("jupyter-notebook.ipynb")
-        elements.should == [[type: 'JupyterCell', cellType: 'code', snippet: 'from pandas import read_csv\nfrom IPython.display import display', lang: 'python'],
+        elements.should == [[type: 'Snippet', snippet: 'from pandas import read_csv\nfrom IPython.display import display', lang: 'python', className: "znai-jupyter-cell", lineNumber: ""],
                             [type: 'JupyterCell', cellType: 'empty-output', meta: [rightSide: true]],
-                            [type: 'JupyterCell', cellType: 'code', snippet: "tran = read_csv('transport.csv')\nprint(tran)", lang: 'python'],
-                            [type: 'JupyterCell', cellType: 'output', text: '   a   b   c\n' +
+                            [type: 'Snippet',  snippet: "tran = read_csv('transport.csv')\nprint(tran)", lang: 'python', className: "znai-jupyter-cell", lineNumber: "", noGap: true, noGapBorder: true],
+                            [type: 'Snippet', snippet: '   a   b   c\n' +
                                     '0  1   2   3\n' +
-                                    '1  4   5   6\n', meta: [rightSide: true]],
-                            [type: 'JupyterCell', cellType: 'code', snippet: 'display(tran)', lang: 'python'],
+                                    '1  4   5   6', meta: [rightSide: true], className: "znai-jupyter-cell", lineNumber: "", lang: "csv", resultOutput: true],
+                            [type: 'Snippet', snippet: 'display(tran)', lang: 'python', noGap: true, className: "znai-jupyter-cell", lineNumber: ""],
                             [type: 'JupyterCell', cellType: 'output', meta: [rightSide: true], html:'<table border="1" class="dataframe">\n' +
                                     '  <thead>\n' +
                                     '  </thead>\n' +
@@ -54,19 +54,19 @@ class JupyterIncludePluginTest {
                              'JupyterCell'  | 'empty-output' | true
 
                              'JupyterCell'  | 'empty-output' | true
-                             'JupyterCell'  | 'code'         | true
+                             'Snippet'      | ''             | true
 
                              'TestMarkdown' | ''             | false
                              'JupyterCell'  | 'empty-output' | true
 
-                             'JupyterCell'  | 'output'       | false
-                             'JupyterCell'  | 'code'         | true
+                             'Snippet'      | ''             | false
+                             'Snippet'      | ''             | true
 
                              'TestMarkdown' | ''             | false
                              'JupyterCell'  | 'empty-output' | true
 
                              'JupyterCell'  | 'output'       | false
-                             'JupyterCell'  | 'code'         | true  }
+                             'Snippet'      | ''             | true  }
 
     }
 

znai-reactjs/src/App.css

@@ -156,6 +156,7 @@
     --znai-landing-input-placeholder-color: #bbb;
 
     --znai-snippets-background-color: #f8fafc;
+    --znai-snippets-result-output-background-color: #f3f3f3; /* e.g., for combining example and output with noGap */
     --znai-snippets-outer-border-color: #ddd;
     --znai-snippets-inner-border-color: #f3f3f3;
 

znai-reactjs/src/App.jsx

@@ -106,6 +106,7 @@ import { footnoteDemo } from "./doc-elements/footnote/Footnote.demo";
 import { asciinemaDemo } from "./doc-elements/asciinema/Asciinema.demo";
 import { previewConsoleOutputDemo } from "./screens/preview-change-path/PreviewConsoleOutput.demo";
 import { readMoreDemo } from "./doc-elements/read-more/ReadMore.demo.js";
+import { snippetsResultOutputDemo } from "./doc-elements/code-snippets/SnippetResultOutput.demo.jsx";
 
 const docMeta = {
   id: "preview",
@@ -146,6 +147,7 @@ registries
   .add("snippets")
   .registerAsRows("containers title", containerTitleDemo)
   .registerAsGrid("Code Snippet", 0, snippetsDemo)
+  .registerAsGrid("Code Snippet Result Output", 0, snippetsResultOutputDemo)
   .registerAsGrid("Code Snippet With Bullets", 0, snippetsWithInlineCommentsDemo)
   .registerAsGrid("Code Snippet Removed Comments", 0, codeSnippetWithRemovedCommentsDemo)
   .registerAsGrid("Code Snippet Syntax Highlight ", 0, syntaxHighlightSnippetDemo)