Mam projekt razem z kilkoma osobami i mamy README.md
plik z zestawem GitHub Flavored Markdown, który jest renderowany na naszej stronie GitHub. Skonfigurowaliśmy również gałąź GitHub Pages, która jest hostowana w subdomenie naszej organizacji GitHub i użyliśmy automatycznego generatora stron po prostu ładującego się do naszego README.md
pliku podczas tworzenia naszej strony. Jednak zauważam, że kiedy aktualizuję nasz README.md
plik, nie aktualizuje on strony projektu. Zamiast tego musimy przejść do zakładki ustawień GitHub i odtworzyć stronę projektu, przeładowując README.md
plik, gdy to zrobimy.
Ponadto po przeczytaniu o relatywnym łączeniu pracy między plikami dokumentacji na stronach katalogu projektu GitHub. Bardzo podoba mi się przecena, ponieważ oszczędza mnóstwo czasu od konieczności ręcznego pisania całego kodu HTML do naszej dokumentacji. Chciałbym jednak mieć jeden README.md
plik, który może zawierać względne linki do innych plików dokumentacji znajdujących się pod adresem docs/*.md
. Miałem nadzieję, że istnieje proste rozwiązanie, dzięki któremu moje inne pliki dokumentacji mogą również zostać włączone do mojej gałęzi gh-pages i być hostowane w mojej subdomenie GitHub Pages oraz renderowane i / lub tematyczne.
Innymi słowy, moje pytania to:
- Czy istnieje sposób, aby mój plik README.md był automatycznie aktualizowany w subdomenie mojej strony Github?
- [EDYTUJ]: Nie wydaje się być odpowiedzią, jeśli używasz automatycznego generatora stron. Musisz przejść do strony ustawień repozytorium i ponownie ją załadować za każdym razem, gdy nastąpi zmiana, aby ją zaktualizować.
- [EDYTUJ]: Nie wydaje się być odpowiedzią, jeśli używasz automatycznego generatora stron. Musisz przejść do strony ustawień repozytorium i ponownie ją załadować za każdym razem, gdy nastąpi zmiana, aby ją zaktualizować.
- Czy istnieje sposób, aby moje względne linki do mojej dokumentacji w moim pliku README.md działały na moich stronach Github, być może w jakiś sposób zsynchronizuję moje
/docs/*.md
z moimi stronami Github i w jakiś sposób je wyrenderuję i / lub wykorzystam w temacie?- [EDYTUJ]: Z tego, czego się nauczyłem od czasu napisania tego pytania, wynika, że jest to możliwe tylko na stronach GitHub za pomocą statycznego generatora witryn, takiego jak ruby gem Jekyll i prawdopodobnie niektóre zastosowania webhooków obsługiwanych przez GitHub , o których wspomniano w komentarzach poniżej. Obecnie próbuję znaleźć optymalne rozwiązanie.
- [EDYTUJ]: Z tego, czego się nauczyłem od czasu napisania tego pytania, wynika, że jest to możliwe tylko na stronach GitHub za pomocą statycznego generatora witryn, takiego jak ruby gem Jekyll i prawdopodobnie niektóre zastosowania webhooków obsługiwanych przez GitHub , o których wspomniano w komentarzach poniżej. Obecnie próbuję znaleźć optymalne rozwiązanie.
- A jeszcze lepiej, czy istnieje jeszcze łatwiejszy sposób, w jaki mogę to zrobić i być może mam tylko jedną kopię mojego pliku README.md i dokumentacji, która jest używana zarówno na stronach gh, jak i w mojej głównej gałęzi i sprawia, że wszystko jest łatwiejsze?
- [EDYCJA]: Wygląda na to, że ten jest prawie na pewno nie. Myślałem o możliwości wprowadzenia czegoś wbudowanego w GitHub, aby to umożliwić. Wygląda na to, że w przyszłości można by wbudować w GitHub Pages lepsze wsparcie dla tego typu rzeczy, a przynajmniej mam taką nadzieję.
- [EDYCJA]: Wygląda na to, że ten jest prawie na pewno nie. Myślałem o możliwości wprowadzenia czegoś wbudowanego w GitHub, aby to umożliwić. Wygląda na to, że w przyszłości można by wbudować w GitHub Pages lepsze wsparcie dla tego typu rzeczy, a przynajmniej mam taką nadzieję.
źródło
README.md
wersję na strony GitHub?gh-pages
.Odpowiedzi:
Zamierzam opublikować rozwiązanie, które skonfigurowałem, które wykorzystuje fakt, że GitHub Pages korzysta z Jekyll już przy użyciu automatycznego generatora stron.
git checkout gh-pages
mkdir _layouts
mv index.html _layouts
git checkout master -- README.md
mv README.md index.md
index.md
Musisz także otworzyć
index.html
plik i wprowadzić następujące zmiany:Usuń wyrenderowany kod HTML z przeceny w
README.md
pliku. Zwykle jest to między tagami<section>
lub<article>
. Zastąp ten kod HTML tekstem,{{ content }}
który pozwoli nam użyć tego pliku jako jekyll. Plik, do którego zastosujemy układ, zostanie umieszczony w miejscu znacznika treści.Znajdź kod CSS dla motywu strony projektu. dla mnie była to następująca linijka:
<link rel='stylesheet' href='stylesheets/stylesheet.css' />
Należy to zmienić na
<link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />
{{ site.path }}
.W ten sposób Jekyll wyrenderuje plik przeceny jako zawartość
index.html
układu w_layouts
katalogu. Aby zautomatyzować ten proces nie tylko dla pliku README.md, ale także innych dokumentów, które możesz mieć w swojej gałęzi głównej, wykonałem następujące kroki:Utworzono plik o nazwie
post-commit
zawierający:EDYCJA: Zaktualizowałem powyższy skrypt zarówno dla
README.md
pliku, jak i dla przeceny,docs/*
aby używać tego samego pliku układu. To znacznie lepsza konfiguracja niż wcześniej. Ten skrypt trafia do twojego.git/hooks/
katalogu. bash musi być na twojej drodze.Utwórz plik
_config.yml
z następującymPowyższy skrypt synchronizuje również pliki markdown znalezione w
docs/*
katalogumaster
oddziału, aby można je było przeglądać również w witrynie GitHub Pages. Względne łączenie do tych dokumentów działa, jeśli dołączysz następującą funkcję jQuery w celu usunięcia.md
rozszerzenia z kotwic wgh-pages
gałęzi. Możesz dodać poniższy skryptindex.html
w_layouts
katalogu:EDYCJA: Zmieniłem powyższy kod w moim repozytorium, był to szybki i brudny sposób na zrobienie tego, ale nie zadziała to we wszystkich przypadkach, jeśli wiesz, co mam na myśli ... Na przykład plik przeceny
company.mdata.md
nie zostałby przetworzony prawidłowo. Aby to naprawić, zaktualizowałem to do następującego skryptu, który dokładniej sprawdza href i usuwa rozszerzenie, jeśli zostanie znalezione. Skrypt stał się też bardziej ogólny, umożliwiając usuwanie innych rozszerzeń poprzez zmianęext
zmiennej. Oto kod:Skonfigurowałem przykładowe repozytorium w CoryG89 / docsync , który ma tutaj stronę projektu , jeśli chcesz zobaczyć, jak to wszystko działa.
źródło
Moje rozwiązanie problemu z synchronizacją pliku README ze stroną Github różni się nieco od powyższego. Zamiast używać oddzielnego silnika JavaScript Markdown, można użyć interfejsu API Github do zwrócenia pliku Markdown renderowanego jako HTML.
README.md
zhttps://api.github.com/repos/<owner>/<repo>/contents/README.md
.window.atob( JSON.parse( blob ).content );
Opublikuj zdekodowane
README
dohttps://api.github.com/markdown
w treści JSONWstaw wyrenderowany kod HTML do elementu DOM, tak jak zrobił to Brad Rhodes .
Dwa zastrzeżenia do tego podejścia:
W przypadku strony o małym natężeniu ruchu, na której czas wczytywania nie jest krytyczny (~ 1-2 sekundy), powyższa metoda działa wystarczająco dobrze.
źródło
Możesz użyć DocumentUp do renderowania pliku README.md.
źródło
Mam kilka pomysłów na udostępnienie pojedynczego pliku readme między witryną z dokumentacją a głównym repozytorium github:
Możesz użyć tylko jednej gałęzi gh-pages, która zawiera zarówno twój kod, jak i witrynę dokumentacji jekyll. Twoje repozytorium może być trochę zagracone i będziesz musiał umieścić nagłówek YAML na początku pliku readme. To prawie obsługuje względną linkowanie. Problem polega na tym, że jeśli chcesz, aby jekyll wyrenderował Twoją przecenę, nada mu rozszerzenie .html. Może jest jednak sposób, aby to skonfigurować. Oto przykład, który zrzuciłem razem, aby sprawdzić, czy działa.
Możesz użyć wywołań AJAX w swojej witrynie dokumentacji, aby przeczytać plik readme z głównej gałęzi, a następnie wyrenderować go za pomocą mechanizmu renderującego Javascript Markdown . Ładowanie zajmie trochę więcej czasu i nie będzie obsługiwać linków względnych bez napisania sprytnego JavaScript. Wdrożenie wymaga też więcej pracy niż pomysł 1.
źródło
Inną drogą do rozważenia jest ustawienie punktu zaczepienia przed zatwierdzeniem, który buduje odpowiednie strony. Robię to w jednym z moich repozytoriów . Prawdopodobnie musiałbyś jednak zrezygnować z automatycznego generatora stron i po prostu samodzielnie przesłać do
gh-pages
gałęzi, a także zrobić coś wymyślnego, aby zamienić swoje dokumenty w HTML lub witrynę Jekyll, jak sugeruje Nathan .W tym repozytorium naciskam w ten sposób, aby zachować
gh-pages
identycznośćmaster
. Można to zrobić na wiele innych sposobów . Może to jednak nie być idealne dla Twojej sytuacji (możesz nie chcieć, aby były identyczne).W każdym razie powodem, dla którego zaoferowałem nagrodę za to pytanie, było to, że miałem nadzieję, że ktoś ma lepszy przepływ pracy. Ta metoda jest trochę zawiła i nieelastyczna i wymaga od wszystkich synchronizacji haków.
źródło
Inną metodą, którą udało mi się całkiem pomyślnie, jest użycie Ajax do pobierania dokumentów przy użyciu interfejsu API Github i silnika znaczników JavaScript do renderowania HTML (co również zasugerował Nathan).
Nathan wyraził pewne zaniepokojenie wydajnością, ale z mojego doświadczenia wynika, że ładuje się natychmiast, więc nie sądzę, aby to faktycznie był problem.
Zaletą jest to, że jest łatwy w konfiguracji i zawsze zaktualizuje Twoje dokumenty, nawet jeśli edytujesz przecenę bezpośrednio w przeglądarce na github.
Ustawiłem przykład na stronach Github pod adresem http://bradrhodes.github.io/GithubDocSync/, aby pokazać, że działa.
źródło
Inną możliwością dla metody opisanej przez Nathana i Brand Rhodesa jest użycie świetnego narzędzia: FlatDoc stworzonego przez Rico Sta. Cruz.
FlatDoc załaduje przez Ajax dokumentację (README.md lub jakikolwiek inny plik markdown), przeanalizuje ją i wyświetli ze wszystkimi dodatkami, a nawet menu na pasku bocznym do nawigacji!
Ma wbudowaną w swoim api metodę pomocniczą do ładowania plików z repozytorium GitHub (ale może również ładować gdziekolwiek indziej z sieci).
Instrukcje
Zacznij od skopiowania następującego szablonu HTML do swojego index.html w gałęzi gh-pages. Kontynuować:
w pliku. Wypróbuj lokalnie w swojej przeglądarce. Następnie zatwierdź i prześlij zmiany. Teraz twoja strona github będzie zawsze aktualizowana twoim plikiem README.md w twojej gałęzi głównej.
Jeśli domyślny motyw nie jest dla Ciebie satysfakcjonujący, możesz zmienić jego styl za pomocą własnego CSS.
źródło
Chcę również edytować dokumenty w trybie głównym i publikować na stronach gh - lubię aktualizować dokumenty z kodem źródłowym i wydaje się, że to najlepszy sposób. Dla mnie to jest w toku, ale wziąłem skrypt Cory'ego jako punkt wyjścia i rozszerzyłem go trochę, aby działał po wyjęciu z pudełka, o ile istnieje gałąź gh-pages z
_layouts
(tj. Witryna jekyll). Konwertuje szermierkę w stylu backtick (dla bloków kodu), która działa dobrze podczas przeglądania źródeł github, ale nie na stronach gh. Używamindex.md
z dołączeniem do projektu,README.md
więc mogę dodać nagłówek i kilka innych dekoracji. Ta wersja obsługuje również dokumentację w dowolnych zagnieżdżonych katalogach zwanych „docs”, które uważam za przydatne w projekcie z wieloma modułami (nie pod modułami git, tylko podkatalogami):.git/hooks/post-commit
Inną odmianą oryginału jest ustawienie zmiennej
page.home
na wszystkich stronach. Można to wykorzystać do zlokalizowania względnej ścieżki katalogu głównego, dzięki czemu można go użyć do zlokalizowania zasobów statycznych, takich jak css. W_layouts/.default.html
mam:W ten sposób mogę edytować css, lokalnie budować witrynę jekyll i zobaczyć wynik w przeglądarce bez konieczności czekania, aż Github zbuduje ją na serwerze.
źródło
Niedawno stworzyłem pakiet gh-pages-generator, aby rozwiązać ten problem - generuje on wielostronicową witrynę przy użyciu wielu plików MD i pliku konfiguracyjnego.
Prawidłowo aktualizuje wszystkie łącza między stronami. Wprowadzanie zmian z powrotem do gałęzi gh-pages jest stosunkowo łatwe.
Używam go tu i tutaj .
źródło
To nie jest trudne , dwie kopie i wklejanie do terminala i gotowe.
Jekyll
pozwala zaimportować plik markdown, a następnie zajmie się konwersją do formatu HTML. Sztuczka polega na zaimportowaniu plikuREADME.md
doindex.md
pliku z rozszerzeniem{% include_relative README.md %}
. Oto jak możemy to zrobić:Warto sprawdzić, jak skonfigurować
Jekyll
witrynę super szkieletową na githubie (to tylko dwa pliki! )Ustawić
Możesz skopiować oba pliki i uruchomić swoją stronę z aktualnym plikiem readme, uruchamiając tę jednorazową konfigurację ( skopiuj cały blok kodu i przejdź do terminala ):
Automatyzacja
Następnie wystarczy zautomatyzować zadanie kopiowania wszystkich zmian z
master
dogh-pages
gałęzi przed każdym wypchnięciem. Możemy to zrobić, uruchamiając ten skrypt ( możesz go skopiować i wkleić do terminala )Utworzy hak push, który będzie kopiował wszystkie zmiany z
master
gałęzi dogh-pages
każdego uruchomieniagit push
.Otóż to. Gotowe.
źródło