如何解决GitHub无法正确渲染R内核Jupyter Notebook的问题？

问题说明 #

我计划创建一个存储R语言Jupyter Notebook（使用JupyterLab编辑）的GitHub仓库，但通过GitHub网页端打开这些Notebook时，内容显示混乱；将仓库克隆/拉取到本地后，文件在JupyterLab或Jupyter Notebook中可正常使用，说明这并非Git的问题。此前GitHub支持正确渲染R内核的Notebook，想了解是否有办法强制GitHub正常渲染这类Notebook。

示例R代码如下：

df.fer <- read.xlsx("../data/data.xlsx",sheet='fermentation')

# adjusting data, creating factors, adjusting data types, etc.
df.fer$`Volume.[Nml]` <- as.numeric(df.fer$`Volume.[Nml]`) # some text artifacts are present so as.numeric has to be used
df.fer$`disintegration.temp.[oC]` <- factor(df.fer$`disintegration.temp.[oC]`,
                                            ordered=TRUE, levels=c('in.','b.d.','45','50','55','60'))
df.fer$`disintegration.time.[h]` <- factor(df.fer$`disintegration.time.[h]`,
                                           ordered=TRUE,levels=c('in.','0','24','48'))

# creating new factor to distinguish between case No and experiment included in a case
df.fer$case.exp <- factor(paste(df.fer$case.No, df.fer$experiment.No,sep='-'))


# changing the column names for simpler manipulation
df.fer.original.col.names <- colnames(df.fer) # just in case
df.fer.simlified.col.names <- c('day','volume','original.column.header','description','composition','inoculum.weight',
                                'co-substrate.weight','dis.temp','dis.time','case','experiment','disintegration.tab','case.exp')

colnames(df.fer) <- df.fer.simlified.col.names

# removing one series - it turned out to be invalid
bad.series_case.exp <- '35-1' # it will be removed in some analyses
df.fer <- df.fer[df.fer$case.exp != bad.series_case.exp,]

GitHub上的渲染效果：

可行解决方法 #

• 检查并修正Notebook内核元数据：用文本编辑器打开.ipynb文件，查看顶部metadata中的kernelspec字段，确保内容符合R内核的标准格式：

  "kernelspec": {
    "display_name": "R",
    "language": "r",
    "name": "ir"
  }
  

  若language不是小写的r或name有误，修改后保存并提交到仓库，GitHub会根据正确的内核标识渲染内容。

• 本地预渲染为HTML文件：使用nbconvert工具将R Notebook转换成HTML格式，保留原.ipynb文件的同时提交HTML版本：

  jupyter nbconvert --to html your_notebook.ipynb
  

  用户可直接在GitHub网页端打开HTML文件查看正确排版的内容，原Notebook文件仍可用于本地编辑运行。

• 修复Notebook文件格式：部分情况下，Notebook的JSON结构可能存在微小损坏（如多余逗号、格式错位），本地能正常打开但GitHub渲染器无法识别。可通过以下命令修复：

  pip install nbformat
  jupyter nbformat --repair your_notebook.ipynb
  

  修复完成后重新提交文件。

• 使用GitHub Pages部署（可选）：若仓库包含多个Notebook，可将仓库部署到GitHub Pages，借助静态页面渲染机制稳定展示R Notebook内容，避免网页端直接渲染的兼容性问题。

内容的提问来源于stack exchange，提问作者Wojciech Artichowicz