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

Question

我和一些人一起有一个项目,我们有一个README.md文件,里面有一堆GitHub Flavored Markdown,它们在我们的GitHub页面上呈现.我们还建立了一个GitHub Pages分支,它在我们的GitHub组织的子域下托管,并在我们创建页面时使用自动页面生成器简单地加载到我们的README.md文件中.但是,我注意到当我更新README.md文件时,它不会更新项目页面.相反,我们必须转到GitHub设置选项卡并重新创建项目页面,README.md在我们这样做时重新加载文件.

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

换句话说,我的问题是:

• 有没有办法让我的README.md文件自动更新我的Github页子域？
  • [编辑]:如果使用自动页面生成器,似乎没有答案.您必须转到repo的设置页面,并在每次更改时重新加载它以便更新它.
     
• 有没有一种方法,我可以有我的我的文档相对链接在我的README.md档案工作对我Github上的页面,或许是我莫名其妙地同步我的/docs/*.md我的Github上的页面并以某种方式呈现和/或主题化呢？
  • [编辑]:从自写这个问题,我学到的东西,似乎这是唯一可能在GitHub上的页面通过使用的静态站点生成像红宝石宝石化身,可能有些用途由GitHub的支持网络挂接被提及在下面的评论中.我正在尝试寻找最佳解决方案.
     
• 更好的是,有一种更简单的方法可以做到这一点,也许只有一份我的README.md和文档,用于gh页面和我的主分支,并使一切最简单？
  • [编辑]:看来这个几乎肯定是不.我正在考虑GitHub中内置的东西的可能性.似乎未来可能会在GitHub页面中构建对此类事物的更好支持,或者至少我绝对希望它会成为.
     

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. 存储在您网站上的任何其他资产也将需要以此为前缀{{ site.path }}.

通过这样做,Jekyll将markdown文件呈现为目录中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

上面的脚本还同步docs/*在master分支目录中找到的markdown文件,以便它们也可以在GitHub Pages站点上查看.如果包含以下jQuery函数以.md从gh-pages分支上的锚点剥离扩展,则相对链接到这些文档.您可以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上设置了一个示例回购,如果你想看看这一切是如何协同工作的,那么这里有一个项目页面.

Answer 2

我对README与Github页面同步问题的解决方案与上述略有不同.可以使用Github API返回呈现为HTML的Markdown文件,而不是使用单独的JavaScript Markdown引擎.

1. README.md从中获取https://api.github.com/repos/<owner>/<repo>/contents/README.md.
2. 解码Base64响应: window.atob( JSON.parse( blob ).content );

3. 将解码后的内容发布README到https://api.github.com/markdownJSON正文中

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

4. 将呈现的HTML插入DOM元素,就像Brad Rhodes所做的那样.

这种方法有两点需要注意:

1. 执行两个串行请求会减慢页面加载速度.
2. 访问Github API时可能会遇到速率限制.

对于负载时间不重要(~1-2秒)的低流量页面,上述方法运行良好.