it-swarm.dev

Jak mogę zsynchronizować dokumentację z Github Pages?

Mam projekt z kilkoma osobami i mamy plik README.md z wieloma GlavHub Flavored Markdown, który jest renderowany na naszej stronie GitHub. Utworzyliśmy również gałąź GitHub Pages, która jest hostowana w subdomenie naszej organizacji GitHub, i użyliśmy generatora Automatic Page Generator po prostu ładując w naszym pliku README.md, gdy tworzyliśmy naszą stronę. Jednak zauważam, że kiedy aktualizuję nasz plik README.md, nie aktualizuje on strony projektu. Zamiast tego musimy przejść do karty ustawień GitHub i odtworzyć stronę projektu, ponownie ładując plik README.md, gdy to zrobimy. 

Również po przeczytaniu o relative linking 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 napisania całego HTML do naszej dokumentacji. Chciałbym jednak mieć jeden plik README.md, który może zawierać odnośniki względne do innych plików dokumentacji znajdujących się w docs/*.md. Miałem nadzieję, że istnieje łatwe rozwiązanie, aby moje inne pliki dokumentacji mogły być również zawarte w moim oddziale gh-pages i być hostowane w mojej subdomenie GitHub Pages oraz być renderowane i/lub tematyczne.

Innymi słowy, moje pytania to:

  • Czy istnieje sposób na automatyczną aktualizację mojego pliku README.md na subdomenie Github Page?
    • [EDIT]: Nie wydaje się być odpowiedzią, jeśli używasz automatycznego generatora stron. Musisz przejść do strony ustawień repo i przeładować ją za każdym razem, gdy pojawi się zmiana, aby ją zaktualizować.
  • Czy jest jakiś sposób, w jaki mogę mieć moje odnośniki do mojej dokumentacji w moim pliku README.md na moich stronach Github Pages, być może w jakiś sposób synchronizuję mój /docs/*.md z moimi Github Pages i jakoś je renderuję i/lub je motywuję?
    • [EDIT]: Z tego co dowiedziałem się od czasu napisania tego pytania, wydaje się, że jest to możliwe tylko na stronach GitHub poprzez użycie generatora static site jak Ruby Gem Jekyll i prawdopodobnie niektóre zastosowania webhooks obsługiwanych przez GitHub które są wymienione w komentarzach poniżej. Próbuję obecnie próbować znaleźć optymalne rozwiązanie.
  • Jeszcze lepiej, czy jest jeszcze łatwiejszy sposób na zrobienie tego 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 mojej głównej gałęzi i sprawia, że ​​wszystko jest łatwiejsze?
    • [EDIT]: Wygląda na to, że ten jest prawie na pewno nie. Myślałem o możliwości wbudowania czegoś w GitHub, aby to umożliwić. Wydaje się, że lepsze wsparcie dla tego rodzaju rzeczy może być wbudowane w GitHub Pages w przyszłości, a przynajmniej mam nadzieję, że tak będzie.
79
Cory Gross

Zamierzam opublikować rozwiązanie, które konfiguruję, wykorzystując fakt, że GitHub Pages używa już Jekylla, korzystając z automatycznego generatora stron.

  1. git checkout gh-pages
  2. mkdir _layouts
  3. mv index.html _layouts
  4. git checkout master -- README.md
  5. mv README.md index.md
  6. Dodaj następujący tekst do index.md 

---
layout: index
---

Musisz także otworzyć plik index.html i wprowadzić następujące zmiany:

  1. Usuń renderowany HTML z przeceny w pliku README.md. Zazwyczaj jest to między tagami <section> lub <article>. Zastąp ten kod HTML tekstem {{ content }}, który pozwoli nam użyć tego pliku jako jekylla. Plik, do którego zastosujemy układ, zostanie umieszczony w miejscu znacznika treści.

  2. Znajdź CSS dla motywu strony projektu. dla mnie była to linia następująca:

    <link rel='stylesheet' href='stylesheets/stylesheet.css' />

    Należy to zmienić na

    <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

  3. Wszelkie inne zasoby przechowywane w witrynie, które zostaną użyte w tym układzie, będą musiały być poprzedzone znakiem {{ site.path }}.

W ten sposób Jekyll wyrenderuje plik znaczników jako zawartość układu index.html w katalogu _layouts. Aby zautomatyzować ten proces nie tylko dla pliku README.md, ale także dla innych dokumentów, które możesz mieć w swojej gałęzi głównej, podjąłem następujące kroki:

Utworzono plik o nazwie post-commit zawierający następujące elementy:

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following Push if you want to auto Push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git Push Origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDIT: Zaktualizowałem powyższy skrypt zarówno dla pliku README.md, jak i znacznika w docs/*, aby oba używały tego samego pliku układu. Jest to znacznie lepsza konfiguracja niż wcześniej. Ten skrypt znajduje się w katalogu .git/hooks/. bash musi być na twojej drodze.

Utwórz plik _config.yml z następującym kodem

markdown: redcarpet
path: http://username.github.io/reponame

Powyższy skrypt synchronizuje również pliki znaczników znalezionych w katalogu docs/* gałęzi master, aby można je było również wyświetlić na stronie GitHub Pages. Względne powiązanie z tymi dokumentami działa, jeśli uwzględnisz następującą funkcję jQuery w celu usunięcia rozszerzenia .md z kotwic w gałęzi gh-pages. Możesz dodać następujący skrypt do index.html w katalogu _layouts:

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDIT: Zmieniłem powyższy kod w moim repozytorium, to był szybki i brudny sposób na zrobienie tego, ale nie będzie działał we wszystkich przypadkach, jeśli wiesz, co mam na myśli .. Na przykład plik przeceny company.mdata.md nie zostanie poprawnie przetworzony. Aby to naprawić, zaktualizowałem to do następującego skryptu, który dokładniej sprawdza href i usuwa rozszerzenie, jeśli zostanie znalezione. Uczyniłem też skrypt bardziej ogólnym, pozwalając na usunięcie innych rozszerzeń poprzez zmianę zmiennej ext. Oto kod:

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

Skonfigurowałem przykładowy repo w CoryG89/docsync , który ma stronę projektu tutaj , jeśli chcesz zobaczyć, jak to wszystko działa razem.

36
Cory Gross

Moje rozwiązanie problemu synchronizacji README ze stroną Github nieznacznie odbiega od powyższego. Zamiast używać oddzielnego mechanizmu JavaScript Markdown, można użyć API Github, aby zwrócić plik Markdown renderowany jako HTML. 

  1. Pobierz README.md z https://api.github.com/repos/<owner>/<repo>/contents/README.md.
  2. Odkoduj odpowiedź Base64: window.atob( JSON.parse( blob ).content );
  3. Opublikuj zdekodowany plik README na https://api.github.com/markdown w treści JSON

     {
       "text": "<README>",
       "mode": "markdown",
       "context": "<owner>/<repo>"
     }
    
  4. Wstaw renderowany HTML do elementu DOM, tak jak zrobił to Brad Rhodes .

Dwa zastrzeżenia do tego podejścia:

  1. Wykonanie dwóch żądań szeregowych spowalnia ładowanie strony.
  2. Może napotkać limity stawek podczas uzyskiwania dostępu do interfejsu API Github.

Dla strony o małym natężeniu ruchu, gdzie czas ładowania nie jest krytyczny (~ 1-2sek), powyższa metoda działa wystarczająco dobrze.

5
kgryte

Możesz użyć DocumentUp do renderowania pliku README.md.

4
niutech

Mam kilka pomysłów na udostępnienie pojedynczego pliku readme między stroną z dokumentacją a głównym repozytorium github:

  1. Można użyć tylko jednej gałęzi stron gh, która zawiera zarówno kod, jak i stronę dokumentacji jekylla. Twoje repozytorium może być trochę zaśmiecone i będziesz musiał umieścić nagłówek YAML na górze readme. To prawie obsługuje linkowanie względne. Problem polega na tym, że jeśli chcesz, aby jekyll wyrenderował twój znacznik, otrzymasz rozszerzenie .html. Może jednak istnieje sposób, aby to skonfigurować. Oto przykład, który rzuciłem razem, aby sprawdzić, czy to działa.

  2. Możesz użyć wywołań AJAX w witrynie dokumentacji, aby przeczytać readme z głównej gałęzi, a następnie renderować za pomocą Javascript Markdown renderer . Trwa to trochę dłużej i nie będzie obsługiwać linków względnych bez pisania sprytnego Javascript. Jest to także więcej pracy niż pomysł 1.

3
Nathan Breit

Inna droga do rozważenia to ustawienie hak pre-commit , który tworzy odpowiednie strony. Robię to w jednym z moich repozytoriów . Prawdopodobnie musiałbyś porzucić automatyczny generator stron i po prostu nacisnąć samemu gałąź gh-pages, a także zrobić coś ciekawego, aby przekształcić dokumenty w HTML lub stronę Jekyll jako Nathan sugeruje .

W tym repozytorium I Push like this , aby gh-pages był identyczny z master. Aby to zrobić, jest 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 dość zawiła i nieelastyczna i wymaga od wszystkich synchronizacji haków.

3
Matt Kantor

Inną możliwością dla metody opisanej przez Nathana i Branda Rhodesa jest użycie wspaniałego narzędzia: FlatDoc stworzonego przez Rico Stę. Cruz.

FlatDoc załaduje przez ajax dokumentację (README.md lub dowolny inny plik znaczników), przeanalizuje go i wyświetli wszystkie gadżety, a nawet menu paska bocznego do nawigacji!

Ma wbudowaną w api metodę pomocniczą do ładowania plików z repozytorium GitHub (ale może również ładować się z dowolnego miejsca z sieci).

Instrukcje

Zacznij od skopiowania następującego szablonu html do twojego index.html w gałęzi gh-pages. Kontynuować:

  • Zastępowanie „USER” nazwą użytkownika GitHub
  • Zastępowanie „REPO” nazwą repo GitHub
  • Zastępowanie „Twój projekt” nazwą twojego projektu

w pliku. Wypróbuj lokalnie w przeglądarce. Następnie zatwierdz i zmień zmiany. Teraz Twoja strona github będzie zawsze aktualizowana za pomocą pliku README.md w gałęzi głównej.

Jeśli domyślny motyw nie jest dla Ciebie satysfakcjonujący, możesz go zmienić za pomocą własnego css.

2
Khalid Salomão

Inną metodą, z którą udało mi się całkiem nieźle pracować, jest wykorzystanie Ajax do pobrania dokumentów przy użyciu API Github i mechanizmu obniżania Javascript w celu renderowania HTML (co sugeruje również Nathan).

  1. Użyj Github API i JSONP, aby pobrać dokument z Github
  2. Odkoduj zawartość base64 w odpowiedzi z interfejsu API Github
  3. Renderuj przecenę za pomocą mechanizmu obniżania javascript
  4. Wyświetl renderowany HTML

Nathan wyraził pewne zaniepokojenie wydajnością, ale z mojego doświadczenia wynika, że ​​ładuje się od razu, więc nie sądzę, aby był to problem.

Zaletą jest to, że jest łatwy w konfiguracji i zawsze aktualizuje dokumenty, nawet jeśli edytujesz przecenę bezpośrednio w przeglądarce na github.

Skonfigurowałem przykład na stronach Github w http://bradrhodes.github.io/GithubDocSync/ aby pokazać, że działa.

2
Brad Rhodes

Chcę także edytować dokumenty w Master i publikować na stronach gh - lubię aktualizować dokumenty wraz z kodem źródłowym i to wydaje się najlepszym sposobem. Jest to dla mnie praca w toku, ale wziąłem skrypt Cory'ego jako punkt wyjścia i rozwinąłem go trochę, aby działał jak najszybciej, dopóki istnieje gałąź stron gh z _layouts (tj. Jekyll teren). Konwertuje ogrodzenie w stylu backtick (dla bloków kodu), które działa dobrze w przeglądaniu źródeł github, ale nie na stronach gh. Używam index.md z dołączeniem do projektu README.md, więc mogę dodać nagłówek i inne dekoracje. Ta wersja obsługuje również dokumentację w dowolnych zagnieżdżonych katalogach o nazwie „docs”, które uważam za przydatne w projekcie z wieloma modułami (nie podmodułami git, tylko podkatalogami):

.git/hooks/post-commit

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # function to convert a plain .md file to one that renders nicely in gh-pages
    function convert {
        # sed - convert links with *.md to *.html (assumed relative links in local pages)
        # awk - convert backtick fencing to highlights (script from bottom of file)
        sed -e 's/(\(.*\)\.md)/(\1.html)/g' "$1" | awk -f <(sed -e '0,/^#!.*awk/d' $0) > _temp && mv _temp "$1"
    } 

    if ! git show-ref --verify --quiet refs/heads/gh-pages; then
        echo "No gh-pages, so not syncing"
        exit 0
    fi

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    mkdir -p _includes

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    if [ -f README.md ]; then
        cp README.md _includes/
        convert _includes/README.md
        git add README.md
        git add _includes/README.md
    fi

    # Generate index if there isn't one already
    ###################################################################
    if [ ! -f index.md ]; then
        echo -e '---\ntitle: Docs\nlayout: default\n---\n\n{% include README.md %}' > index.md
        git add index.md
    fi

    # Generate a header if there isn't one already
    ###################################################################
    if [ ! -f _includes/header.txt ]; then
        echo -e '---\ntitle: Docs\nlayout: default\nhome: \n---\n\n' > _includes/header.txt
        git add _includes/header.txt
    fi

    # Sync the markdown files in all docs/* directories
    ###################################################################
    for file in `git ls-tree -r --name-only master | grep 'docs/.*\.md'`
    do
        git checkout master -- "$file"
        dir=`echo ${file%/*} | sed -e "s,[^/]*,..,g"`
        cat _includes/header.txt | sed -e "s,^home: .*$,home: ${dir}/," > _temp
        cat "$file" >> _temp && mv _temp "$file"
        convert "$file"
        git add "$file"
    done

    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following Push if you want to auto Push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git Push Origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

exit $?

#!/usr/bin/awk
{
   # Replace backtick fencing (renders well when browsing github) with jekyll directives
   if (/```/) {
      IN = IN?0:1 # Are we already in a fenced section? Toggle.
      if (IN) { # If we are starting a fenced section
         if (/```\s*$/) {
           $0 = $0"text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print $0" %}"
      } else { # ending a fenced section
        print "{% endhighlight %}" 
      }
    } else { # not a fencing line
      if (IN) { # but in a fenced section, so add indent to make sure code is rendered with <pre>
        print "    "$0
      } else {
        print
      }
    }
}

Inną odmianą oryginału jest to, że ustawia zmienną page.home na wszystkich stronach. Można go użyć do zlokalizowania ścieżki względnej katalogu głównego, aby można było go użyć do zlokalizowania zasobów statycznych, takich jak css. W _layouts/.default.html mam:

<link rel="stylesheet" href="{{ page.home }}css/main.css">

W ten sposób mogę edytować css, lokalnie zbudować witrynę jekyll i zobaczyć wynik w przeglądarce bez konieczności czekania, aż github zbuduje ją na serwerze.

1
Dave Syer

To nie jest trudne , dwie kopie i wklej do terminala i wszystko gotowe.

Jekyll pozwala zaimportować plik przeceny, a następnie zajmie się jego konwersją do formatu HTML. Sztuką jest zaimportowanie pliku README.md do pliku index.md za pomocą {% include_relative README.md %}. Oto jak możemy to zrobić:

Warto sprawdzić jak skonfigurować super gołe Jekyll stronę na github (to tylko dwa pliki! )

Ustawić

Możesz skopiować dwa pliki i uruchomić stronę z bieżącym plikiem Readme, po prostu uruchamiając tę ​​ jednorazową konfigurację ( skopiuj plik cały blok kodu i pase do terminalu ):

# Copy our two files to the gh-pages branch
git checkout -b gh-pages &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/_config.yml &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/index.md &&
#
# Commit and publish our page on github
git add -A && git commit -m "Create project github page" &&
git Push --set-upstream Origin gh-pages |
#
git checkout master # go back to master branch

Automatyzacja

Następnie musimy zautomatyzować zadanie kopiowania wszystkich zmian z master do gałęzi gh-pages przed każdym Push. Możemy to zrobić, uruchamiając ten skrypt (, możesz skopiować i wkleić go do terminala )

$(cat > .git/hooks/pre-Push << EOF
#!/bin/sh
we_are_in_gh_pages="\$(git branch | grep -G "* gh-pages")"

if [ ! "\$we_are_in_gh_pages" ];
  then
    git checkout gh-pages &&
    git rebase master &&
    git Push -f &&
    git checkout master # go back to master branch
fi
EOF
) && chmod 775 .git/hooks/pre-Push

Stworzy hak push, który skopiuje wszystkie zmiany z gałęzi master do gh-pages za każdym razem, gdy uruchomisz git Push.

To wszystko. Gotowe.

0
Marcelo Lazaroni

Niedawno stworzyłem pakiet gh-pages-generator aby rozwiązać ten problem - generuje stronę wielostronicową przy użyciu wielu plików MD i pliku konfiguracyjnego.

Poprawnie aktualizuje wszystkie linki między stronami. Jest stosunkowo łatwo sprawić, że częścią CI jest zatwierdzanie zmian z powrotem do gałęzi stron gh.

Używam go tutaj i tutaj .

0
esp