基于 Gitea 服务端渲染的 Jupyter Notebooks

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

• 你知道吗？我们现在已经开通了微信公众号和哔哩哔哩视频栏目，欢迎关注、点赞、一键三连!
• 点击链接加入群聊【Gitea 官方技术群】：328432459

如何让 Gitea 原生支持渲染 .ipynb 文件

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

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

如何才能生成可读的 HTML 文档

为了向用户显示更有吸引力的东西，我们需要一些 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 文件，我们会得到如下所示的内容：

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

配置 Gitea 的文档渲染器

跟其他配置选项一样，我们可以在 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 中的 markup 和 jupyter 类附加到了代码块 <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！