Lavorare con README.md su github.com [chiuso]

Non ho molta familiarità con il linguaggio di markup leggero utilizzato da GitHub durante l'aggiornamento dei file README.

Dove sono le risorse che posso leggere su come scrivere la sintassi di markup appropriata per i file README / wiki della mia libreria open source?

E c'è uno strumento che posso "rivedere i miei documenti localmente nel mio browser" prima di inviare il README aggiornato al mio repository GitHub?

Il markup in questione è casualmente chiamato Markdown , creato da John Gruber, autore del blog Daring Fireball . La fonte originale di Markdown può essere trovata su Daring Fireball - Markdown .

Ci sono molti dialetti Markdown, la documentazione per Github può essere trovata sulla pagina Github Flavored Markdown .

bel suggerimento da quella pagina:

premi M su qualsiasi pagina Github con un editor Markdown per visualizzare il cheatsheet.

Puoi anche utilizzare la pagina Github Markdown Live Preview per testare i tuoi documenti Markdown.

Aggiornamento 2012-11-08 : sono in corso sforzi per standardizzare la sintassi Markdown. Vedi The Future of Markdown - Jeff Atwood, Coding Horror e W3C Markdown Community Group .

Aggiornamento 2014/09/09 : CommonMark uno standard Markdown e spec è stato rilasciato.

( Ripubblicando questa risposta con alcune modifiche.)

Un po 'tardi per il gioco, ma ho scritto una piccola CLI in Python. Si chiama Grip (Github Readme Instant Preview) . Aggiungendo alla risposta di Patrick, questo ti permetterà di "rivedere i miei documenti localmente nel mio browser".

Installalo con:

$ pip install grip

E per usarlo, semplicemente:

$ grip

Quindi visita localhost:5000per visualizzare il readme.mdfile in quella posizione.

Puoi anche specificare il tuo file:

$ grip CHANGES.md

E cambia la porta:

$ grip 8080

Oppure combina i due precedenti:

$ grip CHANGES.md 8080

Puoi persino eseguire il rendering del markdown aromatizzato a GitHub (ovvero come vengono visualizzati i commenti e i problemi), opzionalmente con il contesto del repository per collegamenti ipertestuali automatici ad altri problemi:

$ grip --gfm --context=username/repo issue.md

Per brevità, vedere il resto delle opzioni e i relativi dettagli utilizzando la guida della CLI:

$ grip -h

Caratteristiche notevoli:

• Rende le pagine in modo che appaiano esattamente come su GitHub
• Blocchi recintati
• API Python
• Naviga tra i file collegati
• Esporta un documento sottoposto a rendering in un file

Spero che questo ti aiuti. Dai un'occhiata .

C'è un bel editor online / live qui:

http://jbt.github.io/markdown-editor/

C'è anche un Previewpulsante su GitHub.

Vedi nello screenshot seguente che questo pulsante appare quando ho fatto clic su Modifica README.md .

IMHO dal vivo editor è migliore di quello attuale disponibile su GitHub.

AGGIORNARE

Solo ora ho scoperto dopo aver cercato Markdowne Visual Studio che se stai usando VS, puoi installare Web Essentials e avere Markdownsupporto direttamente da Visual Studio. Questo è figo!

Esso ha:

• Evidenziazione della sintassi => Colorazione completa per la sintassi Markdown
• Intellisense for embedded languages ​​( W00T ) => La funzionalità del linguaggio incorporato di GitHub è completamente supportata dal supporto per la sintassi del linguaggio `` ``.

• Finestra di anteprima => Visualizza una finestra di anteprima fianco a fianco dell'HTML renderizzato
• Compila in HTML => Fai clic con il pulsante destro del mouse su qualsiasi file Markdown e seleziona Compila markdown in HTML. Questo genererà un file .html nidificato sotto il file Markdown e rimarrà sincronizzato quando il file Markdown cambia.
• Foglio di stile personalizzato => È possibile aggiungere un foglio di stile specifico per la soluzione per controllare gli stili della finestra di anteprima.

Dettagli al riguardo qui .

Nota che da febbraio 2014, con " Differenze prose renderizzate ", puoi anche vedere la versione renderizzata di una differenza su un file markdown:

I commit e le richieste pull, inclusi i file in prosa, ora includono viste di origine e renderizzate .

Le modifiche non di testo vengono visualizzate con una sottolineatura punteggiata di basso profilo. Passa il mouse sul testo per vedere cosa è cambiato:

Un'altra opzione: il nuovo editor di testo di Github, Atom, renderà il markdown in stile Github mentre lo modifichi. Vedi https://atom.io/

Non sono sicuro se sarà gratuito (come nella birra) a lungo termine.

A partire da oggi, puoi visualizzare l'anteprima mentre modifichi il file.

Non ho trovato che gli altri strumenti fossero abbastanza buoni - volevo:

1. Possibilità di modificare offline
2. Non solo il ribasso regolare, ma l'attuale ribasso aromatizzato a GitHub

Questo è ciò su cui alla fine ho deciso: https://github.com/ypocat/gfms

> gfms

Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms

Options:
  -p, --port              Port number to listen at.        [required]
  -h, --host              Host address to bind to.         [default: "localhost"]
  --proxy                 if behind a proxy, proxy url.
  -a, --api               Render using Github API.
  -n, --no-api-on-reload  Disable usage of Github API when the doc is manually reloaded.

Quindi ho alias:

alias gm='gfms -a -p 8070'

L'utilizzo -pdell'opzione colpisce l'API Github e utilizza l'attuale Github CSS corrente, quindi non ci sono sorprese.