Come memorizzare GitHub wiki come parte della sorgente

Question

GitHub (e molti altri git server come GitLab) offrono wiki a livello di progetto dove, in genere, i file markdown (*.md) vengono archiviati e formano ... beh ... il wiki del progetto .

Sarebbe così fresco se ci fosse un modo per memorizzare il wiki come parte della fonte principale del progetto, in modo che quando si preme modifiche al progetto principale, il tuo wiki cambia così (beh, se hai fatto modifiche ai file di markdown wiki che è).

Qualcosa di simile:

myproject/ 
    src/main/resources/ 
    src/main/groovy/ 
    build.grade 
    docs/ 
     Home.md 
     About_This_Project.md 
     etc. 

Esiste un modo per ottenere questo risultato? Vedo che i wiki hanno URL clone e figure che indicano che vengono trattati come progetti Git separati. Un modo per combinare i due?

Answer 1

Come menzionato da @larsks in un commento, è possibile utilizzare GitHub Pages per qualcosa di simile. Tuttavia, senza alcuni strumenti aggiuntivi, la documentazione dovrebbe essere in un ramo separato ("gh-pages") dal progetto principale. Tuttavia, ci sono alcuni modi per fondere i due insieme e alcune delle soluzioni potrebbero essere utilizzate con altri host Git con un piccolo ritocco.

GPH-import

Il pratico strumento ghp-import in realtà prende la directory docs/ (o qualsiasi directory si punta a) e lo copia sopra al ramo gh-pagine per voi (e può opzionalmente spinta per GitHub). Poiché GitHub Pages utilizza Jekyll sotto il cofano, se i tuoi file sono docs/ configurati come progetto Jekyll, ogni volta che esegui il comando ghp-import, le tue modifiche alla documentazione verranno applicate al ramo "gh-pages". Quando tali modifiche vengono inviate a GitHub, eseguono Jekyll nei file Markdown e aggiornano il sito con l'HTML visualizzato.

Naturalmente, ci sono alcuni problemi con questa soluzione. Prima di tutto, è specifico per GitHub e, in secondo luogo, blocca la cronologia di commit del ramo `gh-pages '(vedi warning nella documentazione).

git-sottostruttura

Forse una soluzione più universale è quello di utilizzare git-subtree, che può copiare (e conservare) la storia di una sottodirectory ad un ramo separato. Copierà solo i commit che hanno effettuato la sottodirectory specificata. Inoltre, qualsiasi commit che includesse modifiche sia nella sottodirectory specificata che in altre parti della tua fonte include solo le modifiche alla sottodirectory. Ho fatto una revisione completa su how to use it con GitHub Pages qualche tempo fa.

La versione tipo è quello di eseguire i seguenti comandi dal tuo padrone filiale ogni volta che si desidera aggiornare il ramo gh-pages (o qualsiasi ramo che si sta utilizzando):

git subtree split --branch gh-pages --prefix docs/ 
git push origin gh-pages 

Non usando GitHub

Se Non vuoi usare GitHub, potresti (in teoria) usare uno degli strumenti sopra elencati e configurare un altro telecomando per il ramo che contiene solo la tua documentazione. Quindi, dopo aver copiato le tue modifiche nel ramo della documentazione (magari usando il comando git subtree split), potresti spingere quel ramo nel repository "wiki" del tuo host. Non l'ho provato personalmente. Il tuo chilometraggio può variare.

Non usando Jekyll

Anche GitHub pagine non richiede di utilizzare Jekyll per rendere i vostri documenti. Se si preme già reso HTML su GitHub Pages, funzioneranno perfettamente. Varie static site generators (more here) offrono questo tipo di funzionalità. Ad esempio, un progetto popolare, MkDocs, prenderà i documenti Markdown nella tua dir docs/ e li renderà in HTML. È quindi possibile caricare quei documenti resi su vari servizi di hosting.

Questa risposta si sta pericolosamente avvicinando a raccomandare strumenti specifici, quindi mi fermo qui.

Answer 2

GitHub renderizza i file Markdown nel relativo visualizzatore in modo da poterlo fare efficacemente senza fare nulla. Se si mette un link nel tuo README.md in questo modo:

...to see more info [click Here](docs/SomeFile.md). So on and so forth 

poi, quando un utente fa clic sul link nel vostro README.md, che riceveranno al posto giusto e il file verrà reso come Markdown nel visualizzatore area della finestra.