Rendering in lattice in README.md su Github


134

Esiste un modo per eseguire il rendering di LaTex in README.md in un repository GitHub? L'ho cercato su Google e ho cercato in overflow dello stack, ma nessuna delle risposte correlate sembra fattibile.


1
Non è possibile direttamente. C'è qualcosa di specifico per cui pensi di aver bisogno di LaTex? Ad esempio, se vuoi equazioni matematiche, ciò può essere fattibile con alcuni trucchi specifici. Dicci cosa vuoi rendere e qualcuno potrebbe essere in grado di indicarti una soluzione alternativa.
Waylan,

1
Sì, voglio equazioni matematiche ed equazioni allineate, insieme a simboli matematici in linea. È praticamente tutto.
user90593



1
hai preso in considerazione l'uso dei notebook Jupyter? Ora puoi persino inserire il codice Python;)
Charlie Parker il

Risposte:


42

Per le espressioni brevi e la matematica non così fantasiosa potresti usare l'HTML in linea per ottenere il rendering del tuo lattice in matematica sui codici di codice e quindi incorporare l'immagine risultante. Ecco un esempio:

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

Il che dovrebbe tradursi in qualcosa di simile al prossimo

Aggiornamento: Funziona alla grande in Eclipse ma sfortunatamente non in Github. L'unica soluzione è la prossima:

Prendi la tua equazione in lattice e vai su http://www.codecogs.com/latex/eqneditor.php , nella parte inferiore dell'area in cui viene visualizzata la tua equazione, c'è un piccolo menu a discesa, scegli l'URL codificato e quindi incollalo nel tuo github markdown nel prossimo modo:

![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
Suggerisco di usare latex.codecogs.com/png.latex invece di latex.codecogs.com/gif.latex ; restituisce immagini di qualità migliore!
Steffo,

9
potresti usare latex.codecogs.com/svg.latex, è indipendente dalla risoluzione.
lizardfireman

28

Carico repository con equazioni su Gitlab perché ha il supporto nativo per LaTeX nei file .md:

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

La sintassi per il lattice in linea è $`\sqrt{2}`$ .

Gitlab esegue il rendering delle equazioni con JavaScript nel browser anziché mostrare le immagini, il che migliora la qualità delle equazioni.

Maggiori informazioni qui .

Speriamo che Github attui questo anche in futuro.


Sorprendente! Grazie per la punta :)
Jonathan H

Sai se GitHub ha implementato questo?
Rylan Schaeffer,


21

Readme2Tex

Ho lavorato su uno script che automatizza la maggior parte della cruft dall'ottenere la composizione di LaTeX nel markdown di Github: https://github.com/leegao/readme2tex

Ci sono alcune sfide con il rendering di LaTeX per Github. Innanzitutto, il markdown al gusto di Github rimuove la maggior parte dei tag e la maggior parte degli attributi. Ciò significa che nessuna libreria basata su Javascript (come Mathjax) né qualsiasi stile CSS.

La soluzione naturale sembra quindi essere quella di incorporare immagini di equazioni precompilate. Tuttavia, ti accorgerai presto che LaTeX fa molto di più che trasformare le formule allegate con il simbolo del dollaro in immagini.

inserisci qui la descrizione dell'immagine

La semplice incorporazione di immagini da compilatori online conferisce al tuo documento un aspetto davvero innaturale. In effetti, direi che è ancora più leggibile nel tuo gergo matematico x ^ 2 di tutti i giorni che nel jumpy .

Credo che sia importante accertarsi che i tuoi documenti siano composti in modo naturale e leggibile. Questo è il motivo per cui ho scritto una sceneggiatura che, oltre a compilare formule in immagini, assicura anche che l'immagine risultante sia correttamente adattata e allineata al resto del testo.

Ad esempio, ecco un estratto di un .mdfile relativo ad alcune proprietà enumerative del set di espressioni regolari che utilizza readme2tex:

inserisci qui la descrizione dell'immagine

Come ci si potrebbe aspettare, l'insieme di equazioni in alto viene specificato semplicemente avviando l' align*ambiente corrispondente

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

Si noti che mentre le equazioni in linea ($ ... $) vengono eseguite con il testo, vengono visualizzate le equazioni (quelle delimitate da \begin{ENV}...\end{ENV}o$$...$$ ) vengono centrate. Ciò semplifica la produttività delle persone già abituate a LaTeX.

Se questo suona come qualcosa che potrebbe aiutare, assicurati di verificarlo. https://github.com/leegao/readme2tex


14
Sulla base di questo lavoro ho creato un'app GitHub che automatizza il processo di rendering, innescandolo ogni volta che viene effettuata una spinta. Penso che sia utile, quindi condivido il link per coloro che vogliono provarlo: github.com/agurz/github-texify
agurodriguez

3
Bello! È davvero fantastico da parte tua :)
Lee

L'app TeXify non sembra funzionare quando si include mathjax in linea per gli elementi elencati di markdown.
user32882


13

Ho testato alcune soluzioni proposte da altri e vorrei raccomandare TeXify creato e proposto nei commenti di agurodriguez e ulteriormente descritto da Tom Hale - Vorrei sviluppare la sua risposta e dare qualche motivo per cui questa è un'ottima soluzione:

  • TeXify è il wrapper di Readme2Tex (menzione nella risposta di Lee ). Per utilizzare Readme2Tex devi installare molti software nel tuo computer locale (python, latex, ...) - ma TeXify è un plug-in github quindi non devi installare nulla nel tuo computer locale - devi solo installare online che plugin nel tuo account github premendo un pulsante e scegli i repository per i quali TeXify avrà accesso in lettura / scrittura per analizzare le tue formule tex e generare immagini.
  • Quando nel tuo repository crei o aggiorni un *.tex.mdfile, TeXify rileverà le modifiche e genererà un *.mdfile in cui le formule di lattice verranno scambiate dalle sue immagini salvate nella texdirectory nel tuo repository. Quindi, se si crea il file README.tex.md, TeXify genererà README.md con immagini anziché formule tex. Quindi l'analisi delle formule tex e la generazione della documentazione vengono eseguite automaticamente su ogni commit e push :)
  • Poiché tutte le tue formule vengono modificate in immagini nella texdirectory e il file README.md utilizza collegamenti a tali immagini, puoi anche disinstallare TeXify e tutta la tua vecchia documentazione continuerà a funzionare :). La texdirectory e i *.tex.mdfile rimarranno nel repository in modo da avere accesso alle tue formule e immagini in lattice originali (puoi anche archiviare in sicurezza nella texdirectory le altre immagini della documentazione "fatte a mano" - TeXify non le toccherà).
  • È possibile utilizzare la sintassi del lattice delle equazioni direttamente nel file README.tex.md (senza perdere la sintassi del markdown .md) che è molto utile . Nella sua risposta Julii ha proposto di utilizzare collegamenti speciali (con formule) a servizi esterni, ad es. http://latex.codecogs.com/gif.latex?s%3D%5Ctext%20%7B%20sensor%20reading%20%7Dil che è buono ha tuttavia alcuni svantaggi: le formule nei collegamenti non sono facili (utili) da leggere e aggiornare, e se ci saranno problemi con quel servizio di terze parti la tua vecchia documentazione smetterà di funzionare ... In TeXify la tua vecchia documentazione funzionerà sempre anche se disinstalli quel plugin (perché tutte le tue immagini generate dalle formule di lattice rimangono nella repo nella texdirectory).
  • Lo Yuchao Jiang nella sua risposta, ha proposto di utilizzare Jupyter Notebook, che è anche carino ma presenta alcuni inconvenienti: non è possibile utilizzare le formule direttamente nel file README.md, è necessario creare un collegamento lì con altri file * .ipynb nel repository che contiene lattice (MathJax) formule. Il formato del file * .ipynb è JSON che non è utile da mantenere (ad es. Gist non mostra errori dettagliati con il numero di riga nel file * .ipynb quando hai dimenticato di mettere la virgola nella posizione corretta ...).

Ecco il link ad alcuni dei miei repository in cui utilizzo TeXify per cui è stata generata la documentazione dal file README.tex.md .


@Royi Non lo so
Kamil Kiełczewski,

È bello, ma come gestisci un sacco di immagini svg di immondizia inutilizzate nella cartella / tex?
Serge P.

@SergeP. deliziare tutto e spingere?
Kamil Kiełczewski,

6

Per la conversione automatica al push su GitHub, dai un'occhiata all'app TeXify :

App GitHub che cerca i file con estensione * .tex.md e esegue il rendering delle sue espressioni TeX come immagini SVG

Come funziona (dal repository di origine ):

Ogni volta che si preme TeXify verrà eseguito e cercherà i file * .tex.md nell'ultimo commit. Per ognuno di questi verrà eseguito readme2tex che prenderà le espressioni LaTeX racchiuse tra simboli di dollaro, lo convertirà in semplici immagini SVG e quindi salverà l'output in un file di estensione .md (ciò significa che un file chiamato README.tex.md verrà elaborato e l'output verrà salvato come README.md). Successivamente, il file di output e le nuove immagini SVG vengono quindi sottoposti a commit e rimandati al repository.


1
Quest'opera è di @agurodriguez che la menziona in un commento sopra
icc97

1
@ icc97 sì, ma agurodriguez non crea risposta (e probabilmente non noterò mai il suo commento). Poiché Tom crea una risposta (~ 1 anno dopo agurodriguez), noto che TeXify esiste e mi permette di usare TeXify e scrivere la mia base di risposta su questo. Quindi è stato bello :)
Kamil Kiełczewski

3
@ KamilKiełczewski Non c'è niente di sbagliato in questa risposta, sto solo menzionando che TeXify è stato creato da un utente SO a causa di questa discussione, che è piuttosto interessante.
icc97,

Sto usando TeXify sul mio file Leggimi ma, per qualche motivo, il rendering sta saltando le linee quasi ogni volta che c'è un $...$testo. Qualche idea sul perché? Questo è il repository: github.com/brunoconteleite/Spatial-Model-Solver
Bruno Conte Leite

3

La mia soluzione rapida è questa:

passaggio 1. Aggiungi latex al tuo .mdfile

$$x=\sqrt{2}$$

Nota: gli eqn matematici devono essere in $$ ... $$ o \\(... \\).

passaggio 2. Aggiungere quanto segue al scripts.htmlfile del tema o (aggiungere questo codice alla fine)

<script type="text/javascript" async

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

Fatto!. Vedi la tua eq. caricando la pagina.


1
Quale scripts.htmlfile? Non riesco a trovare alcun riferimento a questo come funzionalità github.
Jay Lemmon,

hai un file di Jeykylltemi ( file di temi)? Questo codice serve per visualizzare il lattice nelle pagine git.
CKM,

2
Dovrebbe chiarire che questo funziona solo per le pagine git, non per README.md nei repository regolari.
germanio

1

È possibile ottenere un servizio di integrazione continua (ad esempio Travis CI ) per il rendering di LaTeX e il commit dei risultati su github. CI distribuirà un lavoratore "cloud" dopo ogni nuovo commit. Il lavoratore compila il documento in pdf e cede ImageMagick per convertirlo in un'immagine o utilizza PanDoc per tentare la conversione LaTeX-> HTML dove il successo può variare a seconda del documento. Il lavoratore quindi trasferisce l'immagine o l'html nel repository da dove può essere mostrato nel file Leggimi.

Di seguito viene incollata la configurazione di esempio di TravisCi che crea un PDF, lo converte in un PNG e lo memorizza in una posizione statica nel repository. Dovresti aggiungere una riga che recupera il PDF converte il PDF in un'immagine

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

Questa configurazione di Travis Ci avvia un lavoratore Ubuntu scarica un'immagine docker in lattice, compila il documento in pdf e lo trasferisce in un ramo chiamato branchanme-pdf.

Per altri esempi, consulta questo repository github e la relativa discussione sx , esempio PanDoc , https://dfm.io/posts/travis-latex/ e questo post su Medium .



Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.