git - 如何将文档与 Github Pages 同步？

Question

我和几个人一起有一个项目，我们有一个 README.md 文件，其中包含在我们的 GitHub 页面上呈现的一堆 GitHub 风格的 Markdown。我们还设置了一个 GitHub Pages 分支，托管在我们 GitHub 组织的子域下，并使用 Automatic Page Generator创建页面时，只需加载我们的 README.md 文件即可。但是，我注意到当我更新我们的 README.md 文件时，它不会更新项目页面。相反，我们必须转到 GitHub 设置选项卡并重新创建项目页面，并在执行此操作时重新加载 README.md 文件。

此外，在阅读了关于 relative linking 的内容之后在 GitHub 项目目录页面上的文档文件之间工作。我非常喜欢 markdown，因为它可以节省大量时间，而不必为我们的文档手动编写所有 HTML。然而，我想要的是能够拥有一个 README.md 文件，该文件能够包含指向位于 docs/*.md 的其他文档文件的相关链接。我希望有一个简单的解决方案，以便我的其他文档文件也可以包含在我的 gh-pages 分支中并托管在我的 GitHub Pages 子域下并进行渲染和/或主题化。

换句话说，我的问题是:

• 有没有办法让我的 README.md 文件在我的 Github Page 子域上自动更新？
  • [ 编辑 ]: 如果使用自动页面生成器，答案似乎不是。您必须转到存储库的设置页面并在每次有更改时重新加载它以更新它。
    
• 有没有办法让我的 README.md 文件上的文档的相关链接在我的 Github 页面上工作，也许我以某种方式将我的 /docs/*.md 同步到我的 Github 页面并以某种方式渲染和/或主题化它们？
  • [ 编辑 ]: 从我写这个问题后学到的知识来看，这似乎只能通过使用 static site generator 在 GitHub 页面上实现。像 ruby 一样 Jekyll可能还有 webhooks supported by GitHub 的一些用途在下面的评论中提到。我目前正在努力寻找最佳解决方案。
    
• 更好的是，有没有一种更简单的方法可以做到这一点，也许只有一份我的 README.md 和在 gh-pages 和我的主分支上使用的文档的副本，并使一切变得最简单？
  • [ EDIT ] : 看来这个几乎肯定是不对的。我在考虑是否可以在 GitHub 中内置一些东西来实现这一点。看来将来可能会在 GitHub Pages 中内置对此类事物的更好支持，或者至少我绝对希望如此。
    

Answer 1

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

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. 将以下文本添加到 index.md

---
layout: index
---

您还需要打开 index.html文件并进行以下更改:

1. 从 README.md 的 markdown 中移除呈现的 HTML文件。这通常介于 <section> 之间。或 <article>标签。将此 HTML 替换为文本 {{ content }}这将允许我们将此文件用作 jekyll。我们应用布局的文件将放置在内容标签所在的位置。

2. 找到项目页面主题的 CSS。对我来说，这是如下一行:

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


   这里需要改成

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


3. 您网站上存储的任何其他将在此布局中使用的 Assets 也需要以 {{ site.path }} 为前缀.

通过这样做，Jekyll 会将 markdown 文件呈现为 index.html 的内容。 _layouts 中的布局目录。为了不仅对 README.md 文件，而且对您的 master 分支中可能拥有的其他文档自动执行此过程，我采取了以下步骤:

创建了名为 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/* 中的 Markdown 两者都使用相同的布局文件。这比我以前的设置要好得多。这个脚本进入你的 .git/hooks/目录。 bash 必须在您的路径中。

创建文件 _config.yml与以下

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

上述脚本还同步了在 docs/* 中找到的 Markdown 文件master 的目录分支，以便它们也可以在 GitHub Pages 站点上查看。如果您包含以下 jQuery 函数以去除 .md，则这些文档的相对链接有效。从 gh-pages 上的 anchor 延伸分支。您可以将以下脚本添加到 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]);
    });
});

编辑: 我在我的存储库中更改了上面的代码，这是一种快速而肮脏的方法，但如果你明白我的意思，它并不是在所有情况下都能正常工作。例如 Markdown 文件 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 设置了一个示例仓库，它有一个 project page here ，如果您想了解所有这些是如何协同工作的。