Utilizzo di README.md su github.com

Question

Non ho molta familiarità con il linguaggio di marcatura 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 inserire il README aggiornato nel mio repository github?

Answer 1

Il markup in questione si chiama casualmente Markdown, creato da John Gruber, autore dello Daring Fireball blog. La fonte originale di Markdown può essere trovata a Daring Fireball - Markdown.

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

bella punta da quella pagina:

stampa M su qualsiasi pagina Github con un editor di Markdown per rivelare il bigino.

È inoltre possibile utilizzare la pagina Github Markdown Live Preview per verificare i documenti Markdown.

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

Aggiornamento 2014-09-09: CommonMark un markdown standard e specifiche è stato rilasciato.

Answer 2

Nota che dal febbraio 2014, con "Rendered Prose Diffs", è anche possibile vedere la versione resa di un diff su un file Markdown:

impegna e tirare le richieste, inclusi i file di prosa ora caratterizzato da viste origine e resi.

cambiamenti non di testo vengono visualizzati con una sottolineatura tratteggiata low-key.Passa il mouse sopra il testo per vedere cosa è cambiato:

Answer 3

non ho trovato che gli altri strumenti erano abbastanza buone - che volevo:

1. Possibilità di modificare offline
2. Non solo un normale markdown, ma lo sconto effettivo di Gitub

Questo è ciò che in ultima analisi, optato per: 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. 

Così ho alias:

alias gm='gfms -a -p 8070' 

Utilizzando l'opzione -p colpisce l'API Github e utilizza l'attuale, corrente Github CSS così non ci sono più ci sono sorprese.

Answer 4

Un'altra opzione: il nuovo editor di testo di Github, Atom, renderizza il markdown github durante la modifica. Vedi https://atom.io/

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

Answer 5

C'è una bella dal vivo online editor/qui:

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

C'è anche un pulsante di Preview a GitHub.

Vedere nello screenshot seguente che questo pulsante viene visualizzato quando ho fatto clic su Modifica su README.md.

IMHO il live editor è meglio di quello attuale disponibile presso GitHub.

UPDATE

Poco fa ho trovato dopo la ricerca di Markdown e Visual Studio che se si sta utilizzando VS, è possibile installare Web Essentials e hanno Markdown supporto direttamente da Visual Studio. Questo è figo!

Ha:

• evidenziazione della sintassi => colorazione completa per Markdown sintassi
• Intellisense per le lingue incorporate (w00t) => caratteristica del linguaggio incorporato di GitHub è completamente il supporto per il supporto per la sintassi del linguaggio `` `.

• finestra di anteprima => vedere una finestra di anteprima side-by-side del rendering HTML
• Compila per HTML => pulsante destro del mouse su qualsiasi file Markdown e selezionare Compila Markdown in HTML. Questo genererà un file .html nidificato sotto il file Markdown e rimarrà sincronizzato mentre il file Markdown cambia.
• Foglio di stile personalizzato => È possibile aggiungere un foglio di stile specifico per soluzione per controllare gli stili della finestra di anteprima.

Dettagli su di esso here.

Answer 6

(Re-posting this answer con alcune modifiche.)

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

Installarlo con:

$ pip install grip 

E per utilizzarlo, è sufficiente:

$ grip 

poi visita localhost:5000 per visualizzare il file readme.md in quella posizione.

È inoltre possibile specificare un tuo file:

$ grip CHANGES.md 

e cambiare la porta:

$ grip 8080 

o combinare i due precedenti:

$ grip CHANGES.md 8080 

Si può anche rendere GitHub- Flavored Markdown (vale a dire come vengono visualizzati i commenti e le problematiche), opzionalmente con il contesto del repository al refere del collegamento ipertestuale automatico NCES al altre questioni:

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

Per brevità, vedere il resto delle opzioni e dei loro dettagli tramite l'aiuto CLI:

$ grip -h 

caratteristiche notevoli:

• Renders pagine di apparire esattamente come su GitHub
• blocchi recintati
• API Python
• Naviga tra legata file
• esporta un documento reso in un file

Spero che questo aiuti. Check it out.

Answer 7

A partire da oggi, è possibile visualizzare l'anteprima mentre si modifica il file.