문서를 Github 페이지와 동기화하려면 어떻게해야합니까?

Question 1

여러 사람과 함께 프로젝트를 진행하고 있으며 README.mdGitHub 페이지에 렌더링되는 GitHub Flavored Markdown이 포함 된 파일이 있습니다. 또한 GitHub 조직의 하위 도메인에서 호스팅되는 GitHub 페이지 분기를 설정 하고 페이지를 만들 때 파일에 로드하기 만하면 자동 페이지 생성기 를 사용했습니다 README.md. 그러나 README.md파일을 업데이트하면 프로젝트 페이지가 업데이트되지 않습니다. 대신 GitHub 설정 탭으로 이동하여 프로젝트 페이지를 다시 생성하여 README.md파일을 다시로드 해야합니다.

또한 GitHub 프로젝트 디렉토리 페이지에서 문서 파일 간의 상대 링크 작업 에 대해 읽은 후 . 문서 작성을 위해 모든 HTML을 직접 작성해야하는 시간을 많이 절약 할 수 있으므로 마크 다운이 매우 마음에 듭니다. 그러나 내가 원하는 것은에있는 README.md다른 문서 파일에 대한 상대 링크를 포함 할 수 있는 하나의 파일 을 가질 수 있다는 것 docs/*.md입니다. 다른 문서 파일도 내 gh-pages 브랜치에 포함되고 내 GitHub Pages 하위 도메인에서 호스팅되고 렌더링 및 / 또는 테마가 될 수 있도록 쉬운 솔루션이 있기를 바랐습니다.

즉, 내 질문은 다음과 같습니다.

내 README.md 파일이 내 Github 페이지 하위 도메인에서 자동으로 업데이트되도록하는 방법이 있습니까?
- [편집] : 자동 페이지 생성기를 사용하는 경우 아니오가 답으로 보입니다. 업데이트하려면 리포지토리의 설정 페이지로 이동하여 변경 사항이있을 때마다 다시로드해야합니다.
내 README.md 파일의 내 문서에 대한 상대 링크가 내 Github 페이지에서 작동하도록 할 수있는 방법이 있습니까? 아마도 /docs/*.md내 Github 페이지와 동기화 하고 어떻게 든 렌더링 및 / 또는 테마를 지정할 수 있습니까?
- [편집] : 이 질문을 작성한 이후로 배운 것에서 이것은 루비 보석 Jekyll 과 같은 정적 사이트 생성기를 사용하여 GitHub 페이지에서만 가능 하며 아마도 언급 된 GitHub 에서 지원 하는 웹훅 의 일부 사용을 통해 가능합니다. 아래 댓글에. 현재 최적의 솔루션을 찾으려고 노력하고 있습니다.
더 좋은 방법은 더 쉽게 할 수있는 방법이 있고 아마도 gh- 페이지와 메인 브랜치 모두에서 사용되는 문서와 README.md의 복사본 하나만 있으면 모든 것을 쉽게 만들 수 있습니까?
- [편집] : 이것은 거의 확실히 아니오 인 것 같습니다. 나는 이것을 허용하기 위해 GitHub에 내장 된 무언가의 가능성에 대해 생각하고있었습니다. 이런 종류의 것에 대한 더 나은 지원이 향후 GitHub 페이지에 구축 될 수있을 것 같거나 적어도 나는 그것이 될 것이라고 확신합니다.

Question 2

GitHub Pages가 이미 자동 페이지 생성기를 사용하고있는 Jekyll을 사용한다는 사실을 활용하여 설정 한 솔루션을 게시 할 것입니다.

git checkout gh-pages
mkdir _layouts
mv index.html _layouts
git checkout master -- README.md
mv README.md index.md
다음 텍스트를 앞에 추가하십시오. index.md

---
layout: index
---

또한 index.html파일 을 열고 다음과 같이 변경해야합니다.

README.md파일 의 마크 다운에서 렌더링 된 HTML을 제거 합니다. 일반적으로 <section>또는 <article>태그 사이에 있습니다. 이 HTML을 텍스트 {{ content }}로 바꾸면이 파일을 지킬로 사용할 수 있습니다. 레이아웃을 적용 할 파일은 콘텐츠 태그가있는 위치에 배치됩니다.
프로젝트 페이지 테마에 대한 CSS를 찾으십시오. 나를 위해 이것은 다음과 같은 줄이었습니다.

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

다음으로 변경해야합니다.

<link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />
이 레이아웃에 사용될 사이트에 저장된 다른 자산도 접두사로 지정해야합니다 {{ site.path }}.

이렇게하면 Jekyll은 마크 다운 파일을 디렉토리 의 index.html레이아웃 내용으로 렌더링합니다 _layouts. README.md 파일뿐만 아니라 마스터 브랜치에있는 다른 문서에 대해서도이 프로세스를 자동화하기 위해 다음 단계를 수행했습니다.

post-commit다음을 포함하는 라는 파일을 생성했습니다 .

#!/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

편집 : 동일한 레이아웃 파일을 사용하도록 README.md파일과 마크 다운 모두에 대해 위의 스크립트를 업데이트했습니다 docs/*. 이전보다 훨씬 나은 설정입니다. 이 스크립트는 .git/hooks/디렉토리에 있습니다. bash는 경로에 있어야합니다.

다음을 사용하여 파일 _config.yml을 만듭니다.

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

위 스크립트는 GitHub 페이지 사이트에서도 볼 수 있도록 브랜치 의 docs/*디렉토리에있는 마크 다운 파일도 동기화 master합니다. 이러한 문서에 대한 상대 링크 .md는 gh-pages분기 의 앵커에서 확장 을 제거하기 위해 다음 jQuery 함수를 포함하는 경우 작동합니다 . 다음 스크립트를 디렉토리 index.html에 추가 할 수 있습니다 _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]);
    });
});

편집 : 내 저장소에서 위의 코드를 변경했습니다.이 작업을 수행하는 빠르고 더러운 방법 이었지만 내가 의미하는 바를 아는 경우 모든 경우에 제대로 작동하지 않습니다. 예를 들어 마크 다운 파일 company.mdata.md이 처리되지 않습니다. 바르게. 이 문제를 해결하기 위해 href를 더 신중하게 확인하고 발견되면 확장을 제거하는 다음 스크립트로 업데이트했습니다. 또한 스크립트를보다 일반화하여 ext변수 를 변경하여 다른 확장을 제거하는 데 사용할 수 있도록했습니다 . 다음은 코드입니다.

$(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));
    });
});

이 모든 것이 어떻게 함께 작동하는지보고 싶다면 여기에 프로젝트 페이지 가있는 CoryG89 / docsync에 예제 저장소를 설정했습니다 .

Question 3

README를 Github 페이지와 동기화하는 문제에 대한 내 솔루션은 위와 약간 다릅니다. 별도의 JavaScript Markdown 엔진을 사용하는 대신 Github API를 사용하여 HTML로 렌더링 된 Markdown 파일을 반환 할 수 있습니다.

에서 가져 README.md옵니다 https://api.github.com/repos/<owner>/<repo>/contents/README.md.
Base64 응답을 디코딩합니다. window.atob( JSON.parse( blob ).content );
디코딩 된 내용 README을 https://api.github.com/markdownJSON 본문에 게시합니다.
```
 {
   "text": "<README>",
   "mode": "markdown",
   "context": "<owner>/<repo>"
 }
```
Brad Rhodes가 수행 한 것처럼 렌더링 된 HTML을 DOM 요소에 삽입합니다 .

이 접근 방식에 대한 두 가지주의 사항 :

두 개의 직렬 요청을 수행하면 페이지로드가 느려집니다.
Github API에 액세스 할 때 속도 제한이 발생할 수 있습니다.

로드 시간이 중요하지 않은 (~ 1-2 초) 트래픽이 적은 페이지의 경우 위의 방법으로 충분합니다.

Question 4

DocumentUp 을 사용하여 README.md를 렌더링 할 수 있습니다 .

Question 5

문서 사이트와 기본 github 저장소간에 단일 readme 파일을 공유하기위한 몇 가지 아이디어가 있습니다.

코드와 jekyll 문서 사이트를 모두 포함하는 단일 gh-pages 브랜치 만 사용할 수 있습니다. 저장소가 약간 복잡해질 수 있으며 readme 상단에 YAML 헤더를 넣어야합니다. 그것은 거의 상대 연결을 지원합니다. 문제는 jekyll이 마크 다운을 렌더링하도록하려면 .html 확장자를 제공한다는 것입니다. 그래도 구성하는 방법이있을 수 있습니다. 작동하는지 확인하기 위해 함께 던진 예가 있습니다.
문서 사이트에서 AJAX 호출을 사용하여 메인 브랜치에서 readme를 읽은 다음 Javascript Markdown 렌더러로 렌더링 할 수 있습니다. 로드하는 데 시간이 조금 더 걸리며 영리한 Javascript를 작성하지 않으면 상대 링크를 지원하지 않습니다. 또한 아이디어 1보다 구현해야 할 작업이 더 많습니다.

Question 6

고려해야 할 또 다른 경로 는 관련 페이지를 빌드 하는 사전 커밋 후크 를 설정하는 것 입니다. 내 저장소 중 하나 에서이 작업을 수행 합니다 . 자동 페이지 생성기를 버리고 gh-pages직접 브랜치로 푸시해야 하며 Nathan이 제안한 대로 문서를 HTML 또는 Jekyll 사이트로 바꾸는 멋진 작업을 수행해야 합니다 .

그 저장소에서 나는 이와 gh-pages동일하게 유지하기 위해 이렇게 푸시 합니다 master. 이를 수행하는 다른 방법 도 많이 있습니다. 그러나 이것은 귀하의 상황에 이상적이지 않을 수 있습니다 (동일하기를 원하지 않을 수도 있습니다).

어쨌든, 제가이 질문에 대해 현상금을 제안한 이유는 누군가가 더 나은 작업 흐름을 갖기를 바라기 때문입니다. 이 방법은 다소 복잡하고 융통성이 없으며 모든 사람이 후크를 동기화 상태로 유지해야합니다.

Question 7

내가 꽤 성공적으로 작업 한 또 다른 방법은 Ajax를 사용하여 Github API와 Javascript 마크 다운 엔진을 사용하여 문서를 가져 와서 HTML을 렌더링하는 것입니다 (Nathan이 제안한대로).

Github API 및 JSONP를 사용하여 Github에서 문서 가져 오기
Github API의 응답에서 base64 콘텐츠 디코딩
자바 스크립트 마크 다운 엔진을 사용하여 마크 다운 렌더링
렌더링 된 HTML 표시

Nathan은 성능에 대해 약간의 우려를 표명했지만 제 경험상 즉시로드되는 것처럼 보이므로 실제로 문제가되지 않는다고 생각합니다.

장점은 설정이 쉽고 github의 브라우저에서 직접 마크 다운을 편집하더라도 항상 문서를 업데이트한다는 것입니다.

http://bradrhodes.github.io/GithubDocSync/의 Github 페이지에 예제를 설정하여 작동하는 모습을 보여주었습니다.

Question 8

Nathan과 Brand Rhodes가 설명한 방법의 또 다른 가능성은 Rico Sta가 만든 FlatDoc 이라는 훌륭한 도구를 사용하는 것 입니다. 크루즈.

FlatDoc은 문서 (README.md 또는 기타 마크 다운 파일)를 ajax로로드하고, 구문 분석하고, 탐색을위한 사이드 바 메뉴와 함께 표시합니다!

API에 GitHub 저장소 마스터에서 파일을로드하는 도우미 메소드를 빌드했습니다 (웹에서 다른 곳에서도로드 할 수 있음).

명령

다음 html 템플릿 을 gh-pages 브랜치의 index.html에 복사하는 것으로 시작하십시오 . 계속 :

"USER"를 GitHub 사용자 이름으로 바꿉니다.
"REPO"를 GitHub 리포지토리 이름으로 바꾸기
"Your Project"를 프로젝트 이름으로 바꾸기

파일에서. 브라우저에서 로컬로 사용해보십시오. 그런 다음 변경 사항을 커밋하고 푸시합니다. 이제 github 페이지가 항상 마스터 브랜치의 README.md 파일로 업데이트됩니다.

기본 테마가 만족스럽지 않다면 자신의 CSS로 스타일을 다시 지정할 수 있습니다.

Question 9

또한 마스터에서 문서를 편집하고 gh-pages에 게시하고 싶습니다. 소스 코드를 사용하여 문서를 최신 상태로 유지하는 것이 가장 좋은 방법 인 것 같습니다. 이것은 저를 위해 진행중인 작업이지만 Cory의 스크립트 를 시작점으로 삼고 gh-pages 브랜치 _layouts(예 : jekyll 사이트) 가있는 한 즉시 작동하도록 약간 확장했습니다 . github 소스 브라우징에서는 잘 작동하지만 gh 페이지에서는 잘 작동하지 않는 백틱 스타일 펜싱 (코드 블록 용)을 변환합니다. 헤더와 다른 장식을 추가 할 수 있도록 index.md프로젝트에 포함과 함께 사용합니다 README.md. 이 버전은 또한 여러 모듈 (git 하위 모듈이 아니라 하위 디렉터리)이있는 프로젝트에서 유용하다고 생각하는 "docs"라는 중첩 된 디렉토리의 문서를 처리합니다.

.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
      }
    }
}

원본의 또 다른 변형은 page.home모든 페이지에 변수 를 설정한다는 것 입니다. 이것은 루트 디렉토리의 상대 경로를 찾는 데 사용할 수 있으므로 css와 같은 정적 리소스를 찾는 데 사용할 수 있습니다. 에서 _layouts/.default.htmlI 있습니다 :

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

이렇게하면 github가 서버에서 빌드 할 때까지 기다릴 필요없이 CSS를 편집하고, jekyll 사이트를 로컬로 빌드하고, 브라우저에서 결과를 볼 수 있습니다.

Question 10

최근에 gh-pages-generator 패키지를 만들었습니다.이 문제를 해결하기 위해 를 여러 MD 파일과 구성 파일을 사용하여 다중 페이지 사이트를 생성합니다.

페이지 간의 모든 링크를 올바르게 업데이트합니다. CI의 일부로 변경 사항을 gh-pages 분기로 다시 커밋하는 것은 비교적 쉽습니다.

나는 그것을 사용하고 여기 와 여기 .

Question 11

어렵지 않아 . 두 번 복사하여 터미널에 붙여 넣으면 모두 설정됩니다.

Jekyll마크 다운 파일을 가져 오면 HTML로 변환됩니다. 트릭은 다음 README.md을 사용하여 index.md파일 로 가져 오는 것 입니다.{% include_relative README.md %} . 이를 수행하는 방법은 다음과 같습니다.

github 에서 슈퍼 베어 본 Jekyll사이트 를 설정하는 방법을 확인해 볼 가치가 있습니다 ( 파일이 두 개 뿐입니다 ! ).

설정

이 한 번의 설정을 실행하여 두 파일을 복사하고 현재 readme와 함께 페이지를 진행할 수 있습니다 ( 전체 코드 블록을 복사하고 터미널에 pase ).

# 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

자동화

그리고 우리는 단지로부터의 모든 변경 복사하는 작업을 자동화 할 필요가 master받는 gh-pages모든 푸시 전에 분기를. 이 스크립트를 실행하여이를 수행 할 수 있습니다 (복사하여 터미널에 붙여 넣을 수 있음 ).

$(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

실행할 때마다 master분기의 모든 변경 사항을 복사하는 푸시 후크를 생성 gh-pages합니다 git push.

그게 다야. 끝난.