[解決済み] Github Pagesとドキュメントを同期させるには？

質問

私は数人の人と一緒にプロジェクトを行っていますが、その中で README.md ファイルに GitHub フレーバー Markdown を記述し、GitHub のページでレンダリングしています。また、GitHub Organization のサブドメインでホストされている GitHub Pages ブランチを立ち上げ、そのブランチ上で 自動ページ生成ツール で読み込むだけで README.md ファイルを読み込むだけです。しかし、私が README.md ファイルを更新しても、プロジェクトページが更新されないことに気づきました。代わりに、GitHub の settings タブでプロジェクトページを再作成し、 ファイルを再読み込みする必要があります。 README.md ファイルを再読み込みしなければなりません。

について読んだ後、また 相対リンク は、GitHub のプロジェクトディレクトリのページで、ドキュメントファイル間を相対リンクしています。マークダウンは、私たちのドキュメントのためにすべてのHTMLを手作業で書かなければならないという時間を大幅に節約してくれるので、とても気に入っています。しかし、私が望むのは、1つの README.md にある他のドキュメントファイルへの相対的なリンクを含むことができる1つのファイルです。 docs/*.md . 私は、他のドキュメントファイルも私の gh-pages ブランチに含まれ、私の GitHub Pages サブドメインの下でホストされ、レンダリングやテーマ設定ができるような簡単なソリューションがあることを望んでいました。

言い換えれば、私の質問は次のとおりです。

• README.mdファイルをGithub Pageのサブドメインで自動的に更新させる方法はありますか？
  • [ 編集 ] : Automatic Page Generatorを使用している場合、Noが答えのようです。更新するためには、レポの設定ページに行き、変更があるたびに再読み込みする必要があります。
    
    
• README.md ファイルにあるドキュメントへの相対リンクを Github ページで使用する方法はありますか？ /docs/*.md をGithubページに同期させ、何らかの方法でそれらをレンダリングおよび/またはテーマ化することができますか？
  • [EDIT ]です。 この質問を書いてから知ったことですが、これはGitHubのページでだけ可能なようです。 静的サイトジェネレータ ruby gem のような ジキル と、おそらくいくつかの使用は GitHub がサポートする webhooks というのがありますが、これは下のコメントで紹介されています。現在、最適な解決策を試行錯誤しています。
    
    
• もっといい方法はないでしょうか。gh-pages と私のメインブランチの両方で使用する README.md とドキュメントのコピーを1つだけ用意して、すべてを簡単にすることはできますか？
  • [編集] : こちらはほぼ間違いなくNOのようです。私は、これを可能にするために GitHub に組み込まれた何かの可能性について考えていました。この種のものに対するより良いサポートが将来的にGitHub Pagesに組み込まれるかもしれませんし、少なくとも私はそうなることを強く望んでいるようです。
    
    

どのように解決するのですか？

私は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. のマークダウンからレンダリングされたHTMLを削除します。 README.md ファイル内のマークダウンからレンダリングされたHTMLを削除します。これは通常 <section> または <article> タグを使用します。このHTMLをテキストに置き換えてください。 {{ content }} とすることで、このファイルをjekyllとして使用することができるようになります。レイアウトを適用したファイルは、contentタグがある場所に配置されます。

2. プロジェクトページのテーマのCSSを探します。私の場合、これは次のような行でした。

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

   これは次のように変更する必要があります。

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

3. このレイアウトで使用される、サイト上に保存されているその他のアセットも、プレフィックスとして {{ site.path }} .

このようにすることで、Jekyllは、マークダウンファイルの内容としてレンダリングされます 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

EDITです。 上のスクリプトを更新して、両方の README.md ファイルとマークダウンの docs/* のマークダウンの両方が同じレイアウトファイルを使用するようにしました。これは、私が以前持っていたものよりずっと良い設定です。このスクリプトはあなたの .git/hooks/ ディレクトリに置きます。bashはパスに含まれている必要があります。

ファイルを作成します。 _config.yml を次のように記述します。

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

上記のスクリプトはまた、マークダウンファイルを docs/* ディレクトリにあるマークダウンファイルも同期します。 master ブランチの ディレクトリに配置し、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]);
    });
});

EDITです。 私は自分のリポジトリで上記のコードを変更しました。これはこれを行うための迅速かつ汚い方法でしたが、あなたが私が何を意味するか知っている場合、それはすべてのケースで正しく動作しません。例えば、マークダウンファイル 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 を持つ プロジェクト・ページはこちら をご覧ください。