Created by potrace 1.15, written by Peter Selinger 2001-2017 Yuze Zou's HomePage 🇨🇳

Readme2TeX, 支持LaTeX的GitHub Readme

 
  • Yuze Zou
  • 2019年 07月19日
  • 0 阅读

截至目前, GitHub项目页面下的Readme(Markdown)还不支持对$\TeX$语法的渲染, 本文介绍一种相对完美的解决方案。如果Readme中有嵌入公式的需求, 一般可以通过在线latex编辑器生成相应公式的图片链接, 例如codecogs。但是这种方法有两个弊端: 1. 生成的图片比较模糊; 2. 页面打开时需要时间加载, 偶尔可能出现图片无法加载的情况。
而readme2tex这个项目满足了我所有的需求, svg矢量图片, 离线生成(相对路径加载), 并且无论是inline或block形式, 显示的大小都完美贴合文本内容（Edge上inline显示有问题, Chrome OK）。

项目地址

leegao/readem2tex

依赖

  • $\LaTeX$编译器, 如果平时有使用$\LaTeX$, 那一般是满足的
  • dvisvgm, 搜索该关键词下载解压, 并将其路径添加至环境变量PATH中即可

安装

pip install readme2tex

注: 作者暂时未将pip中的版本更新至GitHub项目中的最新版本, 缺失的主要功能是--pngtrick, 这一点稍后介绍。

语法

python -m readme2tex --nocdn --output README.md INPUT.md

其中INPUT.md是包含LaTeX的readme文件, 而README.md是由readme2tex工具生成的可在GitHub上显示LaTeX公式的readme。
--nocdn选项目前来看是必须的选项, 其作用是将生成的公式svg图像保存至本地, 并在README.md中以相对路径索引对应的公式图片, 而不是上传至rawgit。如此处理的原因是rawgit的作者因为安全原因已经关闭了该服务。
而在INPUT.md文件中, 通过$ $与$$ $$分别表示inline和block格式的公式即可, readme2tex将为每一个公式生成相应的svg图片, 并存储于svg/文件夹下。
而上述提到的--pngtrick方法是将svg图片进一步转化为png格式, 以便在GitHub项目readme页面可以索引。（此前, 出于安全考虑, GitHub不提供svg格式的相对索引, 但目前已取消该限制。因此, 没有必要再将svg图片转化为png格式。）
此外, 该工具还支持usepackage命令, 其对$\LaTeX$的支持相当完善。更多的使用说明可以参看项目的readme文档。

中文支持

原作者的项目中并未考虑对中文等非ASCII编码的字符集, 导致在使用时若文档中有中文字符则会报错, 报错信息如下:

Traceback (most recent call last):
  File "C:\Users\yuze\Anaconda3\envs\r2l\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "C:\Users\yuze\Anaconda3\envs\r2l\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\yuze\Anaconda3\envs\r2l\lib\site-packages\readme2tex\__main__.py", line 160, in <module>
    args.bustcache)
  File "C:\Users\yuze\Anaconda3\envs\r2l\lib\site-packages\readme2tex\render.py", line 129, in render
    content = readme_file.read()
  File "C:\Users\yuze\Anaconda3\envs\r2l\lib\encodings\cp1252.py", line 23, in decode
    return codecs.charmap_decode(input,self.errors,decoding_table)[0]
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position 86: character maps to <undefined>

原因在于, render.py中调用open()方法使用了缺省的encoding参数, 那么就是使用本机的encoding方式, 但是可能默认的编码方式不支持中文, 导致此处报错。相应地, 我们可以修改对应读写部分的代码, 我将其encoding参数设置为了utf-8, 如此, 只需在编写readme文件时将其保存为utf-8即可与之匹配, 相应改动后的项目地址为: zouyu4524/readme2tex。

搜索