mirror of
https://github.com/go-gitea/gitea.git
synced 2026-06-15 20:25:18 +02:00
### Summary Closes #37308 Adds native rendering support for Jupyter notebook files (`.ipynb`) in Gitea using backend rendering, allowing users to view formatted notebooks with code cells, markdown, outputs, and visualizations directly in the repository browser. ### Motivation Jupyter notebooks are widely used in data science, machine learning, and scientific computing. Currently, Gitea displays `.ipynb` files as raw JSON, making them difficult to read. This feature enables users to view notebooks in a formatted, readable way similar to GitHub and GitLab. ### Implementation Approach **Evolution:** Initially implemented frontend rendering using `marked` and `Shiki` libraries. After review feedback, migrated to backend rendering for better performance, security, and consistency with Gitea architecture. #### Backend Rendering Advantages - Server-side HTML generation eliminates client-side parsing overhead - Integrates with Gitea existing markup sanitizer for security - Uses Chroma for syntax highlighting (consistent with code files) - Uses Goldmark for markdown rendering (consistent with `.md` files) - No additional frontend dependencies required - Better performance for large notebooks ### Features #### Supported Cell Types - **Markdown cells:** Rendered with Goldmark (tables, lists, links, code blocks, etc.) - **Code cells:** Syntax-highlighted with Chroma, execution counts, language detection from notebook metadata - **Output cells:** Multiple output types in a single cell #### Supported Output Types - ✅ Text/plain outputs - ✅ Images (PNG, JPEG, SVG) with base64 data URIs - ✅ HTML outputs (tables, DataFrames, formatted text) - ✅ LaTeX/math equations (rendered as code blocks) - ✅ Error outputs with traceback (styled in red) - ✅ Stream outputs (`stdout`/`stderr`) - ⚠️ Interactive widgets (Plotly, ipywidgets) show informative messages - ⚠️ JavaScript outputs show security warning (disabled for safety) #### Edge Cases Handled - Empty notebooks or notebooks with no outputs - Corrupted JSON with graceful error display - Mixed output types in single cell - Large base64-encoded images - Execution count of `null` or `0` - `nbformat` version compatibility (only renders `nbformat 4+`, shows message for older versions) ### Changes #### Backend (Go) - `modules/markup/jupyter/jupyter.go` (**NEW**) - Jupyter notebook renderer implementation - Parses `.ipynb` JSON structure and generates HTML - Integrates Chroma for code syntax highlighting - Integrates Goldmark for markdown cell rendering - Dynamic language detection from notebook metadata - Handles all standard Jupyter output types - Comprehensive error handling with user-friendly messages - `modules/markup/renderer.go` (**MODIFIED**) - Registered Jupyter renderer in markup system - `main.go` (**MODIFIED**) - Import Jupyter renderer package for initialization #### Styling (CSS) - `web_src/css/markup/jupyter.css` (**NEW**) - Comprehensive styling for notebook cells, code, outputs - Uses Gitea CSS variables for consistent theming - Responsive layout with proper spacing - Table styling for DataFrame outputs - Removed parent container padding for consistency with other renderers #### Sanitizer Rules - `modules/markup/jupyter/jupyter.go` → `SanitizerRules()` - Configured HTML sanitization rules for safe rendering: - Cell structure (markdown, code, input/output wrappers) - Code highlighting (Chroma classes) - Images (base64 data URIs only) - Tables (DataFrames) - Markdown elements (headers, lists, links, etc.) ### Security Considerations - Server-side rendering: No client-side JavaScript execution - HTML sanitization: Strict allowlist for HTML elements and attributes - Image security: Only base64 data URIs allowed (no external URLs) - JavaScript disabled: `application/javascript` outputs show warning - XSS protection: Gitea markup sanitizer handles all HTML output ### Testing Manual testing performed with various notebooks: - Markdown rendering (headers, lists, tables, links, code blocks) - Code cells with execution counts and syntax highlighting - Multiple output types (text, images, HTML, LaTeX, errors, streams) - Error handling for edge cases - Theme compatibility (light/dark mode) ### Screenshots <img width="1080" height="553" alt="image" src="https://github.com/user-attachments/assets/aef9afa7-ed96-434d-98b0-b160565fc967" /> <img width="1092" height="552" alt="image" src="https://github.com/user-attachments/assets/6e61e792-4737-41c1-851e-5c375c1f932a" /> <img width="1104" height="622" alt="image" src="https://github.com/user-attachments/assets/4ac630c1-3a75-4e1c-9bba-c0a27484d001" /> <img width="1104" height="529" alt="image" src="https://github.com/user-attachments/assets/33750c47-70de-4ab2-893d-e5d09fa8d9c4" /> <img width="1111" height="343" alt="image" src="https://github.com/user-attachments/assets/52107d9f-0e06-420b-9ab4-1603dcd676b1" /> <img width="1091" height="650" alt="image" src="https://github.com/user-attachments/assets/0addae21-efa4-44bb-a56e-0418e3d4d227" /> <img width="1077" height="298" alt="image" src="https://github.com/user-attachments/assets/a3a8c5be-638c-45ff-82f3-816264254ead" /> ### Dependencies No new dependencies required: - Chroma (existing) - Syntax highlighting - Goldmark (existing) - Markdown rendering - Standard library - JSON parsing ### Key Design Decisions - Backend rendering for performance and security - Reuses existing Gitea infrastructure (Chroma, Goldmark, sanitizer) - Consistent styling with other markup renderers - Graceful degradation for unsupported features --- **Development Note:** This PR was developed with assistance from Amazon Q Developer and Claude AI for implementation, debugging, and testing. --------- Signed-off-by: Karthik Bhandary <34509856+karthikbhandary2@users.noreply.github.com> Co-authored-by: karthik.bhandary <karthik.bhandary@kfintech.com> Co-authored-by: wxiaoguang <wxiaoguang@gmail.com> Co-authored-by: bircni <bircni@icloud.com>
58 lines
1.4 KiB
Go
58 lines
1.4 KiB
Go
// Copyright 2014 The Gogs Authors. All rights reserved.
|
|
// Copyright 2016 The Gitea Authors. All rights reserved.
|
|
// SPDX-License-Identifier: MIT
|
|
|
|
package main
|
|
|
|
import (
|
|
"os"
|
|
"runtime"
|
|
"strings"
|
|
"time"
|
|
|
|
"gitea.dev/cmd"
|
|
"gitea.dev/modules/log"
|
|
"gitea.dev/modules/setting"
|
|
|
|
// register supported doc types
|
|
_ "gitea.dev/modules/markup/console"
|
|
_ "gitea.dev/modules/markup/csv"
|
|
_ "gitea.dev/modules/markup/jupyter"
|
|
_ "gitea.dev/modules/markup/markdown"
|
|
_ "gitea.dev/modules/markup/orgmode"
|
|
|
|
"github.com/urfave/cli/v3"
|
|
)
|
|
|
|
// these flags will be set by the build flags
|
|
var (
|
|
Version = "development" // program version for this build
|
|
Tags = "" // the Golang build tags
|
|
)
|
|
|
|
func init() {
|
|
setting.AppVer = Version
|
|
setting.AppBuiltWith = formatBuiltWith()
|
|
setting.AppStartTime = time.Now().UTC()
|
|
}
|
|
|
|
func main() {
|
|
cli.OsExiter = func(code int) {
|
|
log.GetManager().Close()
|
|
os.Exit(code)
|
|
}
|
|
app := cmd.NewMainApp(cmd.AppVersion{Version: Version, Extra: formatBuiltWith()})
|
|
_ = cmd.RunMainApp(app, os.Args...) // all errors should have been handled by the RunMainApp
|
|
// flush the queued logs before exiting, it is a MUST, otherwise there will be log loss
|
|
log.GetManager().Close()
|
|
}
|
|
|
|
func formatBuiltWith() string {
|
|
version := runtime.Version()
|
|
if len(Tags) == 0 {
|
|
return " built with " + version
|
|
}
|
|
|
|
return " built with " + version + " : " + strings.ReplaceAll(Tags, " ", ", ")
|
|
}
|