-
-
Notifications
You must be signed in to change notification settings - Fork 186
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: shortcode for Jupyter Notebook (#337)
* feat: shortcode for Jupyter Notebook * chore: update generated CSS files * chore: add example Jupyter Notebook file * chore: update doc * chore: enhance jupyter notebook styling - use raw markdown for contents like code block and markdown text * feat: support load notebook from assets and remote - update docs accordingly - add example notebook file * chore: rename example file
- Loading branch information
Showing
10 changed files
with
433 additions
and
7 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| .hextra-jupyter-code-cell { | ||
| scrollbar-gutter: auto; | ||
|
|
||
| @apply hx-mt-6; | ||
|
|
||
| .hextra-jupyter-code-cell-source { | ||
| @apply hx-text-sm; | ||
| .chroma, | ||
| pre { | ||
| @apply hx-m-0; | ||
| } | ||
| } | ||
|
|
||
| .hextra-jupyter-code-cell-outputs-container { | ||
| @apply hx-text-xs hx-overflow-hidden hx-border hx-border-t-0 hx-rounded-b-xl dark:hx-border-neutral-800; | ||
|
|
||
| .hextra-jupyter-code-cell-outputs { | ||
| @apply hx-overflow-auto hx-max-h-[50vh]; | ||
|
|
||
| pre { | ||
| @apply hx-p-4; | ||
| } | ||
| } | ||
| } | ||
| } | ||
|
|
||
| .hextra-jupyter-code-cell:has(.hextra-jupyter-code-cell-outputs) .hextra-jupyter-code-cell-source .chroma { | ||
| @apply hx-rounded-b-none; | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| --- | ||
| title: "Jupyter Notebook Component" | ||
| linktitle: "Jupyter Notebook" | ||
| math: true | ||
| sidebar: | ||
| exclude: true | ||
| --- | ||
|
|
||
| {{< callout >}}Experimental feature to include Jupyter Notebooks via a shortcode. Note that not all cell types are supported.{{< /callout >}} | ||
|
|
||
| [Jupyter Notebook](https://jupyter.org/) is a language-agnostic HTML notebook application for [Project Jupyter](https://jupyter.org/). It allows you to create and share documents that contain live code, equations, visualizations, and narrative text. | ||
|
|
||
| <!--more--> | ||
|
|
||
| ## How to use | ||
|
|
||
| ### Using a local notebook | ||
|
|
||
| To use the Jupyter Notebook shortcode, you need to have a Jupyter Notebook file in your project. Similar to how you would [add images](../../organize-files#add-images) to the project, you can add Jupyter Notebooks to the `assets` folder. | ||
|
|
||
| {{< filetree/container >}} | ||
| {{< filetree/folder name="assets" >}} | ||
| {{< filetree/file name="notebook.ipynb" >}} | ||
| {{< /filetree/folder >}} | ||
| {{< filetree/folder name="content" >}} | ||
| {{< filetree/folder name="docs" >}} | ||
| {{< filetree/file name="my-page.md" >}} | ||
| {{< /filetree/folder >}} | ||
| {{< /filetree/folder >}} | ||
| {{< /filetree/container >}} | ||
|
|
||
| Include the Jupyter Notebook in the page using the `jupyter` shortcode: | ||
|
|
||
| ```markdown {filename="content/docs/my-page.md"} | ||
| --- | ||
| title: My Page | ||
| math: true | ||
| --- | ||
|
|
||
| {{%/* jupyter "notebook.ipynb" */%}} | ||
| ``` | ||
|
|
||
| Alternatively, you can utilize the [page bundles][page-bundles] feature of Hugo to organize the Jupyter Notebooks together with the Markdown file. | ||
|
|
||
| {{< filetree/container >}} | ||
| {{< filetree/folder name="content" >}} | ||
| {{< filetree/folder name="docs" >}} | ||
| {{< filetree/folder name="my-page" >}} | ||
| {{< filetree/file name="index.md" >}} | ||
| {{< filetree/file name="notebook.ipynb" >}} | ||
| {{< /filetree/folder >}} | ||
| {{< /filetree/folder >}} | ||
| {{< /filetree/folder >}} | ||
| {{< /filetree/container >}} | ||
|
|
||
| ```markdown {filename="content/docs/my-page/index.md"} | ||
| --- | ||
| title: My Page | ||
| math: true | ||
| --- | ||
|
|
||
| {{%/* jupyter "notebook.ipynb" */%}} | ||
| ``` | ||
|
|
||
| ### Using a remote notebook | ||
|
|
||
| You can also use a remote notebook by providing the URL to the notebook file. For example, to include [What is the Jupyter Notebook](https://github.com/jupyter/notebook/blob/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb) notebook in the page, you can use the following shortcode: | ||
|
|
||
| ``` | ||
| {{%/* jupyter "https://raw.githubusercontent.com/jupyter/notebook/main/docs/source/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.ipynb" */%}} | ||
| ``` | ||
|
|
||
| ## Example Notebook | ||
|
|
||
| {{< callout type="info" >}}The following is an example of a notebook file that is included in the project assets folder.{{< /callout >}} | ||
|
|
||
| {{% jupyter "example.ipynb" %}} | ||
|
|
||
| [page-bundles]: https://gohugo.io/content-management/page-bundles/#leaf-bundles |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,81 @@ | ||
| {{/* Render Jupyter Notebook */}} | ||
| {{- $path := .Get 0 -}} | ||
| {{- $data := "" -}} | ||
| {{- $page := .Page -}} | ||
|
|
||
| {{- $isLocal := not (urls.Parse $path).Scheme -}} | ||
| {{- $isPage := and (eq .Page.Kind "page") (not .Page.BundleType) -}} | ||
|
|
||
| {{/* https://gohugo.io/functions/transform/unmarshal/ */}} | ||
| {{- if (not $isLocal) -}} | ||
| {{- with resources.GetRemote $path -}} | ||
| {{- with unmarshal .Content -}}{{- $data = . -}}{{- end -}} | ||
| {{- else -}} | ||
| {{- errorf "Remote resource not found: %s" $path -}} | ||
| {{- end -}} | ||
| {{- else if (not $isPage) -}} | ||
| {{- with .Page.Resources.Get $path -}} | ||
| {{- with unmarshal .Content -}}{{- $data = . -}}{{- end -}} | ||
| {{- else -}} | ||
| {{- errorf "Local resource not found: %s" $path -}} | ||
| {{- end -}} | ||
| {{- else -}} | ||
| {{- with resources.Get $path -}} | ||
| {{- with unmarshal .Content -}}{{- $data = . -}}{{- end -}} | ||
| {{- else -}} | ||
| {{- errorf "Local resource not found: %s" $path -}} | ||
| {{- end -}} | ||
| {{- end -}} | ||
|
|
||
| {{- $language := index $data "metadata" "language_info" "name" | default "python" -}} | ||
|
|
||
| {{- with index $data "cells" -}} | ||
| {{- range $cell := . -}} | ||
| {{- if eq (index $cell "cell_type") "code" -}} | ||
| {{- $source := index $cell "source" -}} | ||
| {{- $sourceContent := (cond (reflect.IsSlice $source) (delimit $source "") $source) -}} | ||
| {{- with ($sourceContent | strings.Chomp) -}} | ||
| {{ (printf "\n\n```%s\n%s\n```\n" $language .) | safeHTML -}} | ||
| {{- end -}} | ||
|
|
||
| <div class="hextra-jupyter-code-cell hextra-scrollbar"> | ||
| {{- $outputs := index $cell "outputs" -}} | ||
| {{- with $outputs -}} | ||
| <div class="hextra-jupyter-code-cell-outputs-container"> | ||
| <div class="hextra-jupyter-code-cell-outputs"> | ||
| {{- range $output := . -}} | ||
| {{- if eq (index $output "output_type") "display_data" -}} | ||
| {{- $data := index $output "data" -}} | ||
| {{- $image := index $data "image/png" -}} | ||
| {{- if $image -}} | ||
| <img src="data:image/png;base64,{{- $image -}}" alt="image" /> | ||
| {{- end -}} | ||
| {{- else if eq (index $output "output_type") "stream" -}} | ||
| {{- $text := index $output "text" -}} | ||
| {{- $textContent := (cond (reflect.IsSlice $text) (delimit $text "") $text) -}} | ||
| <pre class="not-prose hx-text-sm">{{- $textContent -}}</pre> | ||
| {{- else if eq (index $output "output_type") "execute_result" -}} | ||
| {{- $data := index $output "data" -}} | ||
| {{- $text := index $data "text/plain" -}} | ||
| {{- $textContent := (cond (reflect.IsSlice $text) (delimit $text "") $text) -}} | ||
| <pre class="not-prose hx-text-sm">{{- $textContent -}}</pre> | ||
| {{- $html := index $data "text/html" -}} | ||
| {{- if $html -}} | ||
| {{- $htmlText := delimit $html "" -}} | ||
| <div> | ||
| {{- $htmlText | safeHTML -}} | ||
| </div> | ||
| {{- end -}} | ||
| {{- end -}} | ||
| {{- end -}} | ||
| </div> | ||
| </div> | ||
| {{- end -}} | ||
| </div> | ||
| {{- else if eq (index $cell "cell_type") "markdown" -}} | ||
| {{- $source := index $cell "source" }} | ||
| {{- $sourceContent := (cond (reflect.IsSlice $source) (delimit $source "") $source) }} | ||
| {{ (printf "\n%s\n" $sourceContent) | safeHTML }} | ||
| {{- end -}} | ||
| {{- end -}} | ||
| {{- end -}} |