Non è necessario reinventare il sito Web di pubblicare alcuni documenti per il vostro progetto. Approfitta delle pagine GitHub per costruire quasi point-and-click siti doc.
Con Terrence Dorsey2015/03/04
Documentazione progetti software non deve essere difficile. La parte di scrittura è difficile da evitare (se avrò alcuni suggerimenti su che più tardi). Si può prendere cura della parte dell'editoria abbastanza facilmente, tuttavia, senza cadere nella tana del coniglio di scrivere il proprio framework CMS o Web - anche se questi continuano ad essere le strategie di procrastinazione popolari per gli sviluppatori che preferisce scrivere il codice che la documentazione.
Ecco il trucco: Se si sta utilizzando il tuo codice GitHub repository di origine, è possibile usufruire del servizio di built-in Pages GitHub dispongono di pubblicare, di accoglienza, e anche costruire e rendere la documentazione Web-based.
Basta che ospita il sito della documentazione di per sé non è una tale impresa incredibile. In questi giorni di solito è un processo semplice per far girare un server e spingere il tuo sito. Solitamente, ma non sempre. Ci sono i costi di tempo e denaro per impostare e gestire un server Web, anche se si sta lavorando da soli. E questa è la migliore delle ipotesi. Prova la navigazione del big-società la burocrazia per ottenere un server approvato ... e questo è prima di navigare il big-processi aziendali IT per ottenere installato e funzionante.
D'altra parte, se si dispone di un account di GitHub, GitHub pagine si presenta come parte del pacchetto. Se si dispone di depositi privati, come ad esempio attraverso un conto GitHub aziendale, è possibile anche sfruttare le funzioni di autenticazione e autorizzazione organizzazione built-in per limitare chi può vedere e contribuire alla documentazione pubblicata con GitHub Pages.
GitHub ha i wiki, ma sono fortemente limitato di funzionalità rispetto a GitHub Pages, che ha accesso a praticamente qualsiasi cosa si potrebbe impiegare per un sito Web normale compreso CSS personalizzato, JavaScript, framework Web, la compilazione automatica e più.
Così come funziona tutta questa magia? Prendiamo GitHub Pages per un giro con due semplici progetti che dimostrano le basi.
HTML statico
La versione più semplice di un progetto GitHub Pagine coinvolge tre elementi: un repository, un ramo GH-pagine per il progetto in file di progetto e HTML che di pronti contro termine nel ramo gh-pagine spinto al repo. Questo è tutto.
GitHub prende tutti i file HTML nel ramo GH-pagine e serve come un sito Web presso l'URL http: // [accountName] .github.io / [repoName]. Così, per esempio, ho creato un progetto di esempio che vive al http://tpdorsey.github.io/simple-docs/ . Ecco una breve passeggiata attraverso il processo per la creazione di un sito come questo.
In primo luogo, se non siete già lavorando con Git e GitHub, controllare il mio aprile 2014 articolo, " controllo del codice sorgente di Git e Mercurial , "per i collegamenti al software e tutorial. Per questo primo esempio, avrete solo bisogno Git e un account GitHub. Il Git sito ha un download per Windows che include Git Bash e Git Gui, e vi posso assicurare che sia il lavoro bene anche su Windows 10 Technical Preview.
Sulla macchina, creare una cartella per un nuovo progetto, quindi inizializzare il repository Git:
git init
Prima di fare qualsiasi altra cosa, creare e passare al ramo gh-pagine. Non c'è davvero alcun motivo per lavorare in master per questi file:
git checkout -b gh-pagine
Creare una pagine Web coppia. Ho creato un file index.html e una pagina secondaria, page1.html. Per questo progetto le pagine devono essere pagine Web reali, proprio come ci si crea per qualsiasi altro sito. La mia semplice file è in Listato 1 .
Listing 1: Il mio file index.html semplice
Può essere semplice o complicato come volete, ma devono essere file HTML statici.
Commit i file:
add git.
git commit -m "Guardate ma! Documentation"
Ora vai a GitHub e creare un repository per la documentazione. GitHub vi mostrerà un esempio del comando per impostare questo nuovo repo come il telecomando, che farete per il vostro repo doc locale:
GIT aggiungere remota origine [posizione repo]
Ora è possibile spingere i file dal repo documentazione locale di un ramo gh-pagine su GitHub:
git origine spinta gh-pagine
E questo è tutto! GitHub elabora automaticamente file validi nel ramo gh-pagine. Con pagine statiche come quello in figura 1 , le modifiche dovrebbero essere disponibili immediatamente sul sito GitHub Pages. Come ho detto prima, l'URL del sito segue un modello comune, utilizzando il nome dell'account e il nome repo. È inoltre possibile trovare l'URL nella pagina Impostazioni per il repo GitHub.
[Clicca sull'immagine per ingrandirla.] Figura 1. GitHub Renders file HTML in un GH-Pages Branch come Pages GitHub sito
Vuoi includere CSS o JavaScript? Battere se stessi fuori.
Basta ricordarsi di spingere le modifiche al ramo gh-pagine del vostro repo remoto per averli visualizzati nelle pagine ospitate. Inoltre, le pagine sono visibili agli stessi utenti che hanno accesso al tuo repo: repos pubblici hanno siti pubblici, mentre i pronti contro termine privati hanno siti visibili solo agli utenti a cui hai dato accesso repo.
Utilizzando Jekyll
Un'opzione più sofisticato per la creazione di siti per le pagine GitHub è usare Jekyll (vedi figura 2 ), un rubino , su modelli generatore sito web statico basato. Jekyll è stato scritto da Tom Preston-Werner, un co-fondatore di GitHub, ed è nativamente supportato da Pages GitHub.
[Clicca sull'immagine per ingrandirla.] Figura 2. predefinito Jekyll Site
Con Jekyll, il contenuto è scritto in Markdown file di testo formattato per, insieme ad alcuni YAML metadati e configurazione. Jekyll utilizza anche il Liquid motore di template.
Quando si crea un sito Jekyll, Jekyll prende i tuoi contenuti Markdown e modelli di liquidi, insieme a tutti i CSS, script, immagini o altri contenuti che hai specificato, e costruisce un sito HTML statico che è possibile ospitare ovunque. L'aspetto interessante della relazione GitHub-Jekyll, tuttavia, è che non spingere il vostro sito al repo GitHub. Invece, il contenuto di origine e la configurazione viene spinto al repo. GitHub gestisce la costruzione del HTML e spingendolo verso il sito di hosting.
Ottenere Ruby e Jekyll impostati su sistemi Linux o Mac è semplice. "Apt-get rubino," se necessario, poi "gem install Jekyll."
Su Windows, dell'installazione e della configurazione richiede un po 'più di sforzo. La migliore guida in questo momento è di Julian Thilo " Run Jekyll su Windows . " Ho seguito questo su una macchina con Windows 10 Technical Preview e, ancora una volta, assicuro che funziona.
Una volta che tutto è impostato, aprire un prompt dei comandi con Ruby, passare alla cartella in cui si desidera impostare il progetto, ed eseguire "Jekyll nuova" seguito da un nome di cartella per il sito:
Jekyll nuovi Jekyll-docs
cd Jekyll-docs
Quando il sito è stato creato, è già impostato come un repository Git locale. Aggiungere un progetto GitHub per esso, controlla un ramo gh pagine localmente, impostare il telecomando per il vostro repo GitHub, e si è pronti a spingere tutte le modifiche fino a GitHub:
git checkout -b gh-pagine
Avanti, _config.yml aperto in un editor di testo e personalizzare i dettagli di configurazione. La documentazione Jekyll copre tutte le opzioni qui. Un dettaglio importante per i siti ospitati su GitHub Pagine sta definendo la tua "baseurl" per il nome del repository. Ad esempio, se il progetto su GitHub si chiama "Jekyll-docs," l'impostazione URL di base in _config.yml è:
baseurl: "/ Jekyll-docs"
Questo e altri suggerimenti sono spiegati nel Jekyll GitHub pagine di documentazione.
GitHub riconosce il ramo gh-pagine del progetto come progetto Jekyll e ricostruisce automaticamente ogni volta che si preme modifiche. Questo processo richiede un po 'di più di un semplice spingendo verso l'alto HTML, in modo da dare qualche minuto per riflettere i cambiamenti nel vostro sito attuale.
Jekyll Docs Template
Jekyll è un passo in avanti, ma è in realtà concepito come un motore di blog. Si può certamente usare fuori dalla scatola, ma una serie doc bel sta andando a prendere un po 'Giochi per bambini con i modelli, e ho detto questo sarebbe stato facile e veloce.
Di Byron Ruth Jekyll Docs Template (vedi figura 3 ) è un modello di progetto Jekyll personalizzato ottimizzato per flessibilità, documenti multi-pagina. Ha un built-in, tavolo sidebar completamente personalizzabile di contenuti.
[Clicca sull'immagine per ingrandirla.] Figura 3. Jekyll Docs Template è ottimizzato per Documentation Project
Per utilizzare Jekyll Docs Modello, clonare il progetto in una cartella per il progetto:
git clone https://github.com/bruth/jekyll-docs-template.git mio progetto
Dopo che funziona più o meno come qualsiasi altro progetto Jekyll, con due eccezioni. In primo luogo, il progetto include uno script per la creazione di nuovi posti, con la configurazione YAML corretta. Si usa in questo modo:
Nessun commento:
Posta un commento