如何将文档与Github页面同步？

我和几个人一起做了一个项目，我们有一个

README.md

文件，其中有一堆GitHub风格的标记，呈现在我们的GitHub页面上。我们还建立了一个GitHub Pages分支，该分支托管在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页面，并以某种方式呈现和/或设置主题？
  • [编辑]：从我写这个问题以来学到的知识来看，这似乎只有在GitHub页面上使用ruby gem之类的工具才能实现，下面的评论中可能会提到。我正在努力寻找最佳解决方案。
    
• 更好的是，是否有一种更简单的方法可以做到这一点，也许只有一份README.md和文档，可以在gh页面和我的主要分支上使用，让一切变得更简单？
  • [编辑]：看来这一条几乎肯定是不可能的。我在考虑GitHub内置的东西是否有可能实现这一点。看来，将来可能会在GitHub页面中内置对此类内容的更好支持，或者至少我肯定会这样做。
    

---

对于在文档站点和主要github repo之间共享单个自述文件，我有一些想法：

您只能使用一个包含代码和jekyll文档站点的gh pages分支。您的存储库可能会有点混乱，您需要在自述文件的顶部添加YAML标题。它几乎支持相对链接。问题是，如果您想让jekyll呈现您的降价，它会给它一个.html扩展名。也许有一种方法可以配置它

您可以在文档站点中使用AJAX调用从主分支读取自述文件，然后使用。这将需要更长的时间来加载，如果不编写一些聪明的Javascript，它将不支持相对链接。它也比想法1更需要实施

---

另一个要考虑的路径是建立一个构建相关页面的方法。我是在家里做这件事的。不过，你可能不得不放弃自动页面生成器，自己去做

gh页面

分支，同时做一些花哨的事情，将你的文档转换成HTML或Jekyll站点

在该存储库中保持

gh页面

与

master

相同。还有很多方法可以做到这一点。不过，这可能不适合您的情况（您可能不希望它们完全相同）

---

无论如何，我在这个问题上悬赏的原因是因为我希望有人有更好的工作流程。这种方法有点复杂且不灵活，它要求每个人都保持他们的钩子同步。

我将发布一个解决方案，该解决方案利用GitHub Pages使用的Jekyll已经在使用自动页面生成器这一事实进行设置

git签出页面

mkdir\u布局

mv index.html\u布局

git签出主机--README.md

mv README.md index.md

在

index.md

您还需要打开

index.html

文件并进行以下更改：

---

从

README.md

文件中的标记中删除呈现的HTML。这通常介于

或

之间，如果您想了解所有这一切是如何协同工作的，那么这两者之间有一个很大的区别。
我还想在master中编辑文档并在gh页面中发布-我想让文档与源代码保持最新，这似乎是最好的方法。这对我来说是一项正在进行的工作，但我将其作为一个起点，并对其进行了一些扩展，以使其能够开箱即用，只要有一个具有
\u布局的gh pages分支（即一个jekyll站点）。它转换了backtick样式的围栏（用于代码块），这种围栏在github源代码浏览中工作得很好，但在gh页面中不起作用。我使用一个
index.md
和一个包含在项目
README.md
中的include，这样我就可以添加一个标题和一些其他装饰。此版本还处理名为“docs”的任何嵌套目录中的文档，我发现这在具有多个模块（不是git子模块，只是子目录）的项目中很有用：

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

通过这种方式，我可以编辑css，在本地构建jekyll站点，并查看
#!/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

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

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

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

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

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

 {
   "text": "<README>",
   "mode": "markdown",
   "context": "<owner>/<repo>"
 }

# 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

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