Latex-Rendering in README.md auf Github

Für kurze Ausdrücke und nicht so ausgefallene Mathematik könnten Sie den Inline-HTML-Code verwenden, um Ihre Latex-Mathematik in Codecogs zu rendern und das resultierende Bild einzubetten. Hier ein Beispiel:

- <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 " />

Was sollte so etwas wie das nächste ergeben

Update: Das funktioniert gut in Eclipse, aber leider nicht in Github. Die einzige Problemumgehung ist die nächste:

Nehmen Sie Ihre Latex-Gleichung und gehen Sie zu http://www.codecogs.com/latex/eqneditor.php . Am unteren Rand des Bereichs, in dem Ihre Gleichung angezeigt wird, befindet sich ein kleines Dropdown-Menü. Wählen Sie die URL-codierte und dann Fügen Sie das auf die nächste Weise in Ihr Github-Markdown ein:

![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)

Readme2Tex

Ich habe an einem Skript gearbeitet, mit dem die meisten Schurken automatisiert werden, wenn der LaTeX-Satz schön in Github-gewürztem Abzug gebracht wird: https://github.com/leegao/readme2tex

Beim Rendern von LaTeX für Github gibt es einige Herausforderungen. Zunächst werden die meisten Tags und die meisten Attribute mit einem Github-markierten Markdown entfernt. Dies bedeutet keine Javascript-basierten Bibliotheken (wie Mathjax) oder CSS-Styling.

Die natürliche Lösung scheint dann zu sein, Bilder von vorkompilierten Gleichungen einzubetten. Sie werden jedoch schnell feststellen, dass LaTeX mehr als nur Dollarzeichen eingeschlossene Formeln in Bilder umwandelt.

Durch das Einbetten von Bildern aus Online-Compilern erhält Ihr Dokument einen wirklich unnatürlichen Ausdruck. In der Tat würde ich behaupten, dass es in Ihrem täglichen mathematischen Slang sogar lesbarer als sprunghaft ist .

Ich glaube, dass es wichtig ist, sicherzustellen, dass Ihre Dokumente auf natürliche und lesbare Weise gesetzt werden. Aus diesem Grund habe ich ein Skript geschrieben, das nicht nur Formeln in Bilder kompiliert, sondern auch dafür sorgt, dass das resultierende Bild richtig angepasst und an den restlichen Text angepasst wird.

Hier ist zum Beispiel ein Auszug aus einer .md-Datei mit Bezug auf einige Aufzählungseigenschaften von Regelsätzen für reguläre Ausdrücke, die readme2tex verwenden:

Wie zu erwarten, wird der Satz Gleichungen oben angegeben, indem einfach die entsprechende align*-Umgebung gestartet wird

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

Beachten Sie, dass, während Inline-Gleichungen ($ ... $) mit dem Text ausgeführt werden, die angezeigten Gleichungen (die durch \begin{ENV}...\end{ENV} oder $$...$$ begrenzt sind) zentriert sind. Dies macht es für Menschen, die bereits an LaTeX gewöhnt sind, leicht, produktiv zu bleiben.

Wenn dies nach etwas klingt, das helfen könnte, sollten Sie es überprüfen. https://github.com/leegao/readme2tex

Mein Trick ist, das Jupyter Notebook zu verwenden.

GitHub bietet integrierte Unterstützung für das Rendern von .ipynb-Dateien. Sie können Inline schreiben und LaTeX-Code im Notizbuch anzeigen. GitHub wird ihn für Sie rendern.

Hier eine Beispielnotizdatei: https://Gist.github.com/cyhsutw/d5983d166fb70ff651f027b2aa56ee4e

Für die automatische Konvertierung bei Push to GitHub werfen Sie einen Blick auf die TeXify App:

GitHub App, die in Ihren Pushs nach Dateien mit der Erweiterung * .tex.md sucht und deren TeX-Ausdrücke als SVG-Bilder darstellt

Wie es funktioniert (aus dem source Repository ):

Bei jedem Push wird TeXify ausgeführt und sucht nach * .tex.md-Dateien in Ihrem letzten Commit. Für jeden von ihnen wird readme2tex ausgeführt, der LaTeX-Ausdrücke zwischen Dollarzeichen umwandelt, in einfache SVG-Bilder konvertiert und die Ausgabe dann in einer .md-Erweiterungsdatei speichert (das heißt, eine Datei namens README.tex.md wird verarbeitet und die Ausgabe wird als README.md gespeichert. Danach werden die Ausgabedatei und die neuen SVG-Bilder festgeschrieben und in Ihr Repo zurückgeschoben.

Sie können diesen Online-Editor auch verwenden: https://www.codecogs.com/latex/eqneditor.php , das SVG-Dateien im laufenden Betrieb generiert. Sie können einen Link in Ihr Dokument einfügen: ![](https://latex.codecogs.com/svg.latex?y%3Dx%5E2)..

Ich teste einige Lösungen, die von anderen vorgeschlagen wurden, und ich möchte empfehlen TeXify erstellt und in Kommentaren von agurodriguez und weiter beschrieben von Tom Hale - Ich möchte seine Antwort entwickeln und einen Grund angeben warum das eine sehr gute lösung ist:

• TeXify ist ein Wrapper von Readme2Tex (Erwähnung in Lee Antwort ). Um Readme2Tex verwenden zu können, müssen Sie eine Menge Software auf Ihrem lokalen Computer installieren (Python, Latex, ...) - aber TeXify ist ein Github-Plugin, also Sie müssen nichts auf Ihrem lokalen Computer installierenSie müssen nur dieses Plugin online in Ihrem github-Konto installieren, indem Sie eine -Taste drücken und Repositorys auswählen, für die TeXify Lese-/Schreibzugriff haben wird, um Ihre Texformeln zu analysieren und Bilder zu generieren.
• Wenn Sie in Ihrem Repository eine *.tex.md-Datei erstellen oder aktualisieren, erkennt TeXify Änderungen und generiert eine *.md-Datei, in der Latex-Formeln durch ihre Bilder ausgetauscht werden, die im tex-Verzeichnis in Ihrem Repo gespeichert sind. Wenn Sie also die Datei README.tex.md erstellen, generiert TeXify README.md mit Bildern anstelle von Tex-Formeln. Das Parsen von Tex-Formeln und das Generieren von Dokumentation erfolgt automatisch bei jedem Commit & Push :)
• Da alle Ihre Formeln in Bilder im tex-Verzeichnis geändert werden und die README.md-Datei Links zu diesen Bildern verwendet, können Sie Sie können sogar TeXify deinstallieren und Ihre alte Dokumentation funktioniert weiterhin :). Das tex-Verzeichnis und die *.tex.md-Dateien verbleiben im Repository, sodass Sie auf Ihre ursprünglichen Latexformeln und -bilder zugreifen können (Sie können auch Ihre tex-Verzeichnisse Ihrer anderen Dokumentationsbilder "von Hand gemacht" speichern - TeXify wird sie nicht berühren). 
• Sie können die Gleichungslatex-Syntax direkt in der Datei README.tex.md verwenden (ohne die .md-Markdown-Syntax zu verlieren), was sehr praktisch ist. Julii in seiner Antwort schlug vor, spezielle Links (mit Formeln) zu externen Diensten zu verwenden, z. http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7D ist zwar gut, hat jedoch einige Nachteile: Die Formeln in Links sind nicht leicht (praktisch) zu lesen und zu aktualisieren, und wenn es Probleme mit dem Dienst eines Drittanbieters geben sollte, wird Ihre alte Dokumentation nicht mehr funktionieren ... In TeXify Ihre alte Die Dokumentation funktioniert auch dann, wenn Sie das Plugin deinstallieren (da alle Ihre aus Latexformeln generierten Bilder im Repo-Verzeichnis im Verzeichnis tex bleiben).
• Das Yuchao Jiang in seiner Antwort schlug vor, Jupyter Notebook zu verwenden, was auch nett ist, hat jedoch einige Nachteile: Sie können Formeln nicht direkt in der README.md-Datei verwenden, Sie müssen dort einen Link zu einer anderen Datei erstellen. * .ipynb in Ihrem Repo, das Latex-Formeln (MathJax) enthält. Das Format der * .ipynb-Datei ist JSON. Dies ist nicht einfach zu pflegen (z. B. zeigt Gist keinen detaillierten Fehler mit der Zeilennummer in der * .ipynb-Datei, wenn Sie vergessen haben, das Komma an der richtigen Stelle zu setzen ...). 

Hier ist ein Link zu einem Teil meines Repos, bei dem ich TeXify verwende, für das Dokumentation aus README.tex.md generiert wurde.

Ich lade Repositorys mit Gleichungen in Gitlab hoch, da LaTeX in .md-Dateien nativ unterstützt wird:

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

Die Syntax für Inline-Latex lautet $`\sqrt{2}`$.

Gitlab rendert Gleichungen mit JavaScript im Browser, anstatt Bilder anzuzeigen. Dies verbessert die Qualität von Gleichungen.

Mehr Infos hier .

Hoffen wir, dass Github dies auch in Zukunft umsetzen wird.