基于 Gitea 服务端渲染的 Jupyter Notebooks
阅读原文时间:2023年07月08日阅读:2

本指南将向您展示如何通过配置外部渲染器来使 Gitea 呈现 Jupyter Notebooks。当然,你还可以根据本指南来为你的 Gitea 实例配置其他类型的文档渲染器,甚至是二进制文件!相信Gitea,一切皆有可能。

首先,让我们在 Gitea 实例上创建一个新的存储库并将示例笔记本推送上去:

当前,就如我们看到的那样,Gitea 只是将文档的原始内容以纯文本的形式渲染出来——虽然高效但是可读性差。

为了向用户显示更有吸引力的东西,我们需要一些 HTML,幸运的是 Jupyter 有一个名为 nbconvert 的模块:

在 Gitea 服务器上安装我们所需的 nbconvert,它是一个 Python 模块:

sudo apt install python3-pip
pip3 install nbconvert

安装完成,我们可以通过运行命令来测试它,将一个 .ipynb 转换为 .html

jupyter nbconvert --to html --template full path/to/some/test/notebook.ipynb

如果我们在浏览器中打开刚才生成的 .html 文件,我们会得到如下所示的内容:

看起来有戏……让我们继续。

跟其他配置选项一样,我们可以在 custom/conf/app.ini 中添加 jupyter 渲染器。

; Gitea looks for markup.xxxxx and will apply both "markup" and "xxxxx" as a class to the parent <div>
[markup.jupyter]
ENABLED = true
; all the file extensions we want to convert, comma separated.
FILE_EXTENSIONS = .ipynb
; Lets use out nbconvert command from earlier - making to sure to convert to HTML and to output to stdout
RENDER_COMMAND = "jupyter nbconvert --stdout --to html --template full "
; nbconvert accepts a path to a file and not stdin
IS_INPUT_FILE = true

; the name after sanitizer doesn't really matter
[markup.sanitizer.jupyter0]
; Jupyter chiefly uses divs
ELEMENT = div
; we will need access to html classes later
ALLOW_ATTR = class
; we don't mind which classes we keep, so let's keep all of them
REGEXP =

现在让我们看看当我们重新启动 Gitea 时会呈现出什么状况。

如图所示,文档的可读性会比刚开始稍好一些,但仍然与我们之前打开 HTML 时有差距。这是因为 Gitea 禁用了文档的内联样式表以满足网站的安全性需求。而这些内联样式是从封装代码的 <div> 当中的 markup 类继承来的。

如果我们检查之前创建的 HTML 文档内容,会发现几个内联样式:

<style type="text/css">
    /*!
*
* Twitter Bootstrap
*
*/
/*!
 * Bootstrap v3.3.7 (http://getbootstrap.com)
 * Copyright 2011-2016 Twitter, Inc.
 * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
 */
/*! normalize.css v3.0.3 | MIT License | github.com/necolas/normalize.css */
html {
  font-family: sans-serif;
  -ms-text-size-adjust: 100%;
  -webkit-text-size-adjust: 100%;
}
body {
  margin: 0;
}

[...]

</stlye>

找到了解决问题的关键,我们就可以将上面的样式统统剥离下来并将它们组合成一个 jupyter.less 文件,然后删除原来的 <style></style> HTML 标签,如<style></style>

于是,我们就创造了一个包含各种漂亮样式的样式表集合。同时,这个集合也包含了很多通用选择器,例如:

body {
  margin: 0;
}

这些通用选择器肯定会与 Gitea 的默认样式发生冲突。所以我们还需要确保限制了样式的应用范围。幸运的是,Gitea 和 less 可以帮助我们解决这个问题。

将通用选择器按照 less 语法包裹起来:

.someclass {
  body {
    margin: 0;
  }
  summary {
    display: block;
  }
}

上面的代码相也当于 css:

.someclass body {
 margin: 0;
}

.someclass summary {
 display: block;
}

于此同时,Gitea 已将 app.ini 中的 markupjupyter 类附加到了代码块 <div> 上。

因此,让我们将 jupyter.less 的全部内容封装在 .markup.jupyter {} 中,以生成如下所示的内容。

现在让我们将该文件放在我们的 custom 目录中,例如 /root/custom/public/css/jupyter.less

然后将下面的模板添加到 /root/custom/templates/header.tmpl

<!-- lets import the less stylesheet {{AppSubUrl}} is a variable that gitea will autofill -->
<link rel="stylesheet/less" type="text/css" href="{{AppSubUrl}}/css/jupyter.less" />
<!-- we need the javascript to compile the less into css -->
<script src="//cdn.jsdelivr.net/npm/less" ></script>

现在重新启动 Gitea 看看会有什么变化。

呈现使用 .markup.jupyer 自定义样式的最终外观:

看起来不错,但还是出现了一些问题,例如文本溢出了边界。这是由一些肮脏的 CSS 规则引起的,所以我们还需要从 jupyter.less 中删除以下内容:

@media (min-width: 768px) {
  .container {
    width: 768px;
  }
}
@media (min-width: 992px) {
  .container {
    width: 940px;
  }
}
@media (min-width: 1200px) {
  .container {
    width: 1140px;
  }
}

完美的 Jupyter Notebooks!

手机扫一扫

移动阅读更方便

阿里云服务器
腾讯云服务器
七牛云服务器

你可能感兴趣的文章