mirror of
https://github.com/go-gitea/gitea.git
synced 2026-06-15 16:14:10 +00:00
e82352f156
### 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>
Integration tests
Integration tests can be run with command make test-integration.
Environment variable GITEA_TEST_DATABASE can be used to specify the database type for testing.
If you encounter some errors like mismatched database version, SSH push errors, etc.,
you can try to perform a clean build by: make clean build.
Run sqlite integration tests
Start tests directly (empty GITEA_TEST_DATABASE defaults to sqlite):
make test-integration
Run MySQL integration tests
Set up a MySQL database inside docker:
docker run -e "MYSQL_DATABASE=test" -e "MYSQL_ALLOW_EMPTY_PASSWORD=yes" -p 3306:3306 --rm --name mysql mysql:latest #(just ctrl-c to stop db and clean the container)
docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" --rm --name elasticsearch elasticsearch:7.6.0 #(in a second terminal, just ctrl-c to stop db and clean the container)
Start tests based on the database container:
GITEA_TEST_DATABASE=mysql TEST_MYSQL_HOST=localhost:3306 TEST_MYSQL_DBNAME=test TEST_MYSQL_USERNAME=root TEST_MYSQL_PASSWORD='' make test-integration
Run pgsql integration tests
Set up a pgsql database inside docker:
docker run -e "POSTGRES_DB=test" -e "POSTGRES_USER=postgres" -e "POSTGRES_PASSWORD=postgres" -p 5432:5432 --rm --name pgsql postgres:latest #(just ctrl-c to stop db and clean the container)
Set up minio inside docker:
docker run --rm -p 9000:9000 -e MINIO_ROOT_USER=123456 -e MINIO_ROOT_PASSWORD=12345678 --name minio bitnamilegacy/minio:2023.8.31
Start tests based on the database container:
GITEA_TEST_DATABASE=pgsql TEST_MINIO_ENDPOINT=localhost:9000 TEST_PGSQL_HOST=localhost:5432 TEST_PGSQL_DBNAME=postgres TEST_PGSQL_USERNAME=postgres TEST_PGSQL_PASSWORD=postgres make test-integration
Run mssql integration tests
Set up a mssql database inside docker:
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_PID=Standard" -e "SA_PASSWORD=MwantsaSecurePassword1" -p 1433:1433 --rm --name mssql microsoft/mssql-server-linux:latest #(just ctrl-c to stop db and clean the container)
Start tests based on the database container:
GITEA_TEST_DATABASE=mssql TEST_MSSQL_HOST=localhost:1433 TEST_MSSQL_DBNAME=gitea_test TEST_MSSQL_USERNAME=sa TEST_MSSQL_PASSWORD=MwantsaSecurePassword1 make test-integration
Running individual tests
Example command to run GPG test:
GITEA_TEST_DATABASE=... make test-integration#GPG
Run Gitea Actions tests via local act_runner
Run all jobs
act_runner exec -W ./.github/workflows/pull-db-tests.yml --event=pull_request --default-actions-url="https://github.com" -i catthehacker/ubuntu:runner-latest
Warning: This file defines many jobs, so it will be resource-intensive and therefore not recommended.
Run single job
act_runner exec -W ./.github/workflows/pull-db-tests.yml --event=pull_request --default-actions-url="https://github.com" -i catthehacker/ubuntu:runner-latest -j <job_name>
You can list all job names via:
act_runner exec -W ./.github/workflows/pull-db-tests.yml --event=pull_request --default-actions-url="https://github.com" -i catthehacker/ubuntu:runner-latest -l