Латексный рендеринг в README.md на Github


136

Есть ли способ отобразить LaTex в README.md в репозитории GitHub? Я погуглил и искал переполнение стека, но ни один из связанных ответов не кажется возможным.


1
Это невозможно напрямую. Есть ли какая-то конкретная вещь, для которой вам нужен LaTex? Например, если вам нужны математические уравнения, это можно сделать с помощью некоторых специальных приемов. Сообщите нам, что вы хотите отобразить, и кто-нибудь может указать вам обходной путь.
Waylan

1
Да, мне нужны математические уравнения и выровненные уравнения, а также встроенные математические символы. Это почти все.
user90593



1
Вы думали об использовании блокнотов Jupyter? Вы даже можете вставить код Python прямо сейчас;)
Чарли Паркер

Ответы:


43

Для коротких выражений и не столь сложной математики вы можете использовать встроенный HTML, чтобы получить латексную математику на codecogs, а затем встроить полученное изображение. Вот пример:

- <img src="https://latex.codecogs.com/gif.latex?O_t=\text { Onset event at time bin } t " /> 
- <img src="https://latex.codecogs.com/gif.latex?s=\text { sensor reading }  " /> 
- <img src="https://latex.codecogs.com/gif.latex?P(s | O_t )=\text { Probability of a sensor reading value when sleep onset is observed at a time bin } t " />

В результате должно получиться что-то вроде следующего

Обновление: это отлично работает в eclipse, но, к сожалению, не в github. Единственный обходной путь заключается в следующем:

Возьмите латексное уравнение и перейдите на http://www.codecogs.com/latex/eqneditor.php , в нижней части области, где отображается ваше уравнение, есть крошечное раскрывающееся меню, выберите URL-адрес, закодированный, и затем вставьте его в свой github markdown следующим образом:

![equation](http://latex.codecogs.com/gif.latex?O_t%3D%5Ctext%20%7B%20Onset%20event%20at%20time%20bin%20%7D%20t)
![equation](http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D) 
![equation](http://latex.codecogs.com/gif.latex?P%28s%20%7C%20O_t%20%29%3D%5Ctext%20%7B%20Probability%20of%20a%20sensor%20reading%20value%20when%20sleep%20onset%20is%20observed%20at%20a%20time%20bin%20%7D%20t)

4
Я предлагаю использовать latex.codecogs.com/png.latex вместо latex.codecogs.com/gif.latex ; он возвращает изображения лучшего качества!
Steffo

9
вы можете использовать latex.codecogs.com/svg.latex, это не зависит от разрешения.
lizardfireman

28

Я загружаю репозитории с уравнениями в Gitlab, потому что он имеет встроенную поддержку LaTeX в файлах .md:

```math
SE = \frac{\sigma}{\sqrt{n}}
```

Синтаксис встроенного латекса $`\sqrt{2}`$.

Gitlab отображает уравнения с помощью JavaScript в браузере вместо отображения изображений, что улучшает качество уравнений.

Больше информации здесь .

Будем надеяться, что Github реализует это и в будущем.


Удивительный! Спасибо за подсказку :)
Jonathan H

1
Вы знаете, реализовал ли это GitHub?
Райлан Шеффер,

22

Моя уловка - использовать Jupyter Notebook.

GitHub имеет встроенную поддержку для рендеринга файлов .ipynb. Вы можете написать встроенный и отобразить код LaTeX в записной книжке, и GitHub отобразит его за вас.

Вот пример файла записной книжки: https://gist.github.com/cyhsutw/d5983d166fb70ff651f027b2aa56ee4e


21

Readme2Tex

Я работал над сценарием, который автоматизирует большую часть беспорядка, чтобы заставить LaTeX правильно набрать разметку со вкусом Github: https://github.com/leegao/readme2tex

Есть несколько проблем с рендерингом LaTeX для Github. Во-первых, уценка со вкусом Github удаляет большинство тегов и атрибутов. Это означает отсутствие библиотек на основе Javascript (таких как Mathjax) или каких-либо стилей CSS.

Тогда кажется естественным решением встроить изображения предварительно скомпилированных уравнений. Однако вскоре вы поймете, что LaTeX делает больше, чем просто превращает формулы, заключенные в символы доллара, в изображения.

введите описание изображения здесь

Простое встраивание изображений из онлайн-компиляторов придает вашему документу действительно неестественный вид. На самом деле, я бы сказал, что на вашем повседневном математическом сленге x ^ 2 он даже более удобочитаем, чем нервный .

Я считаю, что важно следить за тем, чтобы ваши документы были набраны естественным и читабельным образом. Вот почему я написал сценарий, который, помимо компиляции формул в изображения, также гарантирует, что получившееся изображение будет правильно подогнано и выровнено по остальному тексту.

Например, вот отрывок из .mdфайла, касающийся некоторых перечислительных свойств набора регулярных выражений с использованием readme2tex:

введите описание изображения здесь

Как и следовало ожидать, набор уравнений вверху задается простым запуском соответствующей align*среды.

**Theorem**: The translation $[\![e]\!]$ given by
\begin{align*}
...
\end{align*}
...

Обратите внимание, что в то время как встроенные уравнения ($ ... $) выполняются с текстом, отображать уравнения (те, которые разделены символом \begin{ENV}...\end{ENV}или$$...$$ ) центрируются. Это позволяет людям, которые уже привыкли к LaTeX, оставаться продуктивными.

Если это похоже на то, что может помочь, обязательно проверьте это. https://github.com/leegao/readme2tex


14
На основе этой работы я создал приложение GitHub, которое автоматизирует процесс рендеринга и запускает его каждый раз при нажатии. Думаю, это полезно, поэтому делюсь ссылкой для тех, кто хочет попробовать: github.com/agurz/github-texify
agurodriguez

3
Ницца! Это действительно здорово с вашей стороны :)
Ли

Приложение TeXify, похоже, не работает при включении встроенного mathjax для пронумерованных элементов уценки.
user32882


13

Я тестирую какое-то решение, предложенное другими, и я хотел бы порекомендовать TeXify, созданный и предложенный в комментарии Agurodriguez и дополнительно описанный Томом Хейлом - я хотел бы развить его ответ и объяснить причину, почему это очень хорошее решение:

  • TeXify - это оболочка Readme2Tex (упоминается в ответе Ли ). Чтобы использовать Readme2Tex, вы должны установить много программного обеспечения на свой локальный компьютер (python, latex, ...), но TeXify - это плагин github, поэтому вам не нужно ничего устанавливать на локальном компьютере - вам нужно только онлайн-установку, которая плагин в вашей учетной записи github, нажав один кнопку и выбрав репозитории, для которых TeXify будет иметь доступ на чтение / запись для анализа ваших текстовых формул и создания изображений.
  • Когда вы создаете или обновляете *.tex.mdфайл в своем репозитории , TeXify обнаружит изменения и сгенерирует *.mdфайл, в котором латексные формулы будут заменены его изображениями, сохраненными в texкаталоге вашего репо. Итак, если вы создадите файл README.tex.md, TeXify сгенерирует README.md с изображениями вместо текстовых формул. Таким образом, парсинг текстовых формул и создание документации выполняется автоматически при каждом коммите и нажатии :)
  • Поскольку все ваши формулы превращены в изображения в texкаталоге, а файл README.md использует ссылки на эти изображения, вы даже можете удалить TeXify, и вся ваша старая документация будет работать :). texКаталог и *.tex.mdфайлы будут оставаться в хранилище , так что вы имеете доступ к исходным латексным формулам и картинкам (вы также можете безопасно хранить в texдиректории другой вашей документации фотографии « сделанную вручную» - TeXify не будет их трогать).
  • Вы можете использовать латексный синтаксис уравнений непосредственно в файле README.tex.md (без потери синтаксиса разметки .md), что очень удобно . Юлий в своем ответе предложил использовать специальные ссылки (с формулами) на внешний сервис, например. http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7Dчто хорошо, но имеет некоторые недостатки: формулы в ссылках нелегко (удобно) читать и обновлять, и если возникнут проблемы с этой сторонней службой, ваша старая документация перестанет работать ... В TeXify ваша старая документация будет работать всегда, даже если вы удалите этот плагин (потому что все ваши изображения, созданные на основе латексных формул, остаются в репо в texкаталоге).
  • Yuchao Jiang в своем ответе, предложили использовать Jupyter ноутбук , который также хорошо , однако , имеет недостатки сом , вы не можете использовать формулы непосредственно в README.md файл, вам необходимо сделать ссылку там в другой файл * .ipynb в вашем репо , который содержит латекс (MathJax) формулы. Формат файла * .ipynb - это JSON, который неудобно поддерживать (например, Gist не показывает подробную ошибку с номером строки в файле * .ipynb, когда вы забыли поставить запятую в нужном месте ...).

Вот ссылка на некоторые из моих репозиториев, где я использую TeXify, документация для которого была создана из файла README.tex.md .


@Royi, я не знаю
Камил Келчевски

Это хорошо, но как вы справляетесь с множеством неиспользуемых изображений svg мусора в папке / tex?
Serge P.

@SergeP. Делать все и толкать?
Камил Келчевски

6

Для автоматического преобразования при отправке на GitHub взгляните на приложение TeXify :

Приложение GitHub, которое ищет в ваших пушах файлы с расширением * .tex.md и отображает их TeX-выражения как изображения SVG.

Как это работает (из исходного репозитория ):

Каждый раз, когда вы нажимаете, TeXify будет запускать и искать файлы * .tex.md в вашем последнем коммите. Для каждого из них будет запущен readme2tex, который будет принимать выражения LaTeX, заключенные между знаками доллара, преобразовывать их в простые изображения SVG, а затем сохранять результат в файл с расширением .md (это означает, что файл с именем README.tex.md будет обработан, и результат будет сохранен как README.md). После этого выходной файл и новые изображения SVG фиксируются и отправляются обратно в ваше репо.


1
Эта работа принадлежит @agurodriguez, который упоминает ее в комментарии выше
icc97

1
@ icc97 да, но агуродригез не дает ответа (и я, наверное, никогда не замечу его комментария). Поскольку Том создает ответ (~ 1 год после agurodriguez), я заметил, что TeXify существует, и он позволяет мне использовать TeXify и писать на нем свою собственную базу ответов . Так было хорошо :)
Камил Келчевски

3
@ KamilKiełczewski В этом ответе нет ничего плохого, я просто упоминаю, что TeXify был создан пользователем SO из-за этой темы, что довольно круто.
icc97

Я использую TeXify в моем readme, но по какой-то причине рендеринг перескакивает по строкам почти каждый раз, когда $...$в тексте есть. Какие-нибудь подсказки почему? Это репо: github.com/brunoconteleite/Spatial-Model-Solver
Бруно Конте Лейте

3

Мое быстрое решение таково:

Шаг 1. Добавьте латекс в свой .mdфайл

$$x=\sqrt{2}$$

Примечание: математические выражения должны быть в $$ ... $$ или \\(... \\) .

шаг 2. Добавьте следующее в файл scripts.htmlтемы или (добавьте этот код в конце)

<script type="text/javascript" async

src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">

Готово!. См. Свой эк. загрузив страницу.


1
Какой scripts.htmlфайл? Я не могу найти упоминания об этом как о функции github.
Jay Lemmon

у вас есть файл Jeykyllтемы ( файл темы)? Этот код предназначен для отображения латекса на страницах git.
CKM

2
Следует уточнить, что это работает только для страниц git, а не для README.md в обычном репо.
германий

1

Вы можете получить услугу непрерывной интеграции (например, Travis CI ) для рендеринга LaTeX и фиксации результатов в github. CI будет развертывать «облачного» воркера после каждой новой фиксации. Рабочий компилирует ваш документ в pdf и либо использует ImageMagick для преобразования его в изображение, либо использует PanDoc для попытки преобразования LaTeX-> HTML, где успех может варьироваться в зависимости от вашего документа. Затем Worker фиксирует изображение или html в вашем репозитории, откуда оно может быть показано в вашем файле readme.

Пример конфигурации TravisCi, которая создает PDF-файл, конвертирует его в PNG и фиксирует его в статическом месте в вашем репо, вставлен ниже. Вам нужно будет добавить строку, которая извлекает pdfconverts PDF в изображение

sudo: required
dist: trusty
os: linux
language: generic
services: docker
env:
  global:
  - GIT_NAME: Travis CI
  - GIT_EMAIL: builds@travis-ci.org
  - TRAVIS_REPO_SLUG: your-github-username/your-repo
  - GIT_BRANCH: master
# I recommend storing your GitHub Access token as a secret key in a Travis CI environment variable, for example $GH_TOKEN.
  - secure: ${GH_TOKEN}
script:
- wget https://raw.githubusercontent.com/blang/latex-docker/master/latexdockercmd.sh
- chmod +x latexdockercmd.sh
- "./latexdockercmd.sh latexmk -cd -f -interaction=batchmode -pdf yourdocument.tex -outdir=$TRAVIS_BUILD_DIR/"
- cd $TRAVIS_BUILD_DIR
- convert -density 300 -quality 90 yourdocument.pdf yourdocument.png
- git checkout --orphan $TRAVIS_BRANCH-pdf
- git rm -rf .
- git add -f yourdoc*.png
- git -c user.name='travis' -c user.email='travis' commit -m "updated PDF"
# note we are again using GitHub access key stored in the CI environment variable
- git push -q -f https://your-github-username:$GH_TOKEN@github.com/$TRAVIS_REPO_SLUG $TRAVIS_BRANCH-pdf
notifications:
  email: false

Эта конфигурация Travis Ci запускает рабочий процесс Ubuntu, загружает латексный образ докера, компилирует ваш документ в pdf и фиксирует его в ветке с именем branchanme-pdf.

Дополнительные примеры см. В этом репозитории github и сопутствующем обсуждении sx , примере PanDoc , https://dfm.io/posts/travis-latex/ и в этом сообщении на Medium .



Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.