web-dev-qa-db-ja.com

ドキュメントをGithubページと同期するにはどうすればよいですか？

私は数人のプロジェクトを抱えており、GitHubページにレンダリングされた一連のGitHubフレーバーマークダウンを含むREADME.mdファイルがあります。また、GitHub組織のサブドメインでホストされるGitHub Pagesブランチをセットアップし、 Automatic Page Generator を使用して、単純にREADME.mdファイルをロードしました。私たちのページを作成しました。ただし、README.mdファイルを更新しても、プロジェクトページは更新されないことに気付きました。代わりに、GitHub設定タブに移動してプロジェクトページを再作成し、README.mdファイルをリロードする必要があります。

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

つまり、私の質問は次のとおりです。

  • GithubページのサブドメインでREADME.mdファイルを自動的に更新する方法はありますか？
    • [EDIT]：自動ページジェネレーターを使用している場合、答えは表示されません。リポジトリを更新するには、変更があるたびにリポジトリの設定ページにアクセスしてリロードする必要があります。
  • README.mdファイルのドキュメントへの相対リンクをGithubページで機能させる方法はありますか、おそらく/docs/*.mdをGithubページに何らかの方法で同期し、何とかそれらをレンダリングまたはテーマ設定しますか？
  • さらに良いのは、これを行う簡単な方法はありますか？おそらく、README.mdのコピーとgh-pagesと私のメインブランチの両方で使用され、すべてを最も簡単にするドキュメントを1つだけ持っているでしょうか？
    • [EDIT]：これは間違いなくノーだと思われます。これを可能にするためにGitHubに何かが組み込まれている可能性について考えていました。この種のものに対するより良いサポートが将来GitHub Pagesに組み込まれるかもしれないようです、または少なくとも私はそれが確実にそうなることを望みます。
gitgithubgithub-pageswebhooks
79
Cory Gross

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ファイルのマークダウンから削除します。これは通常、<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はマークダウンファイルを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

上記のスクリプトは、masterブランチのdocs/*ディレクトリにあるマークダウンファイルも同期して、GitHub Pagesサイトでも表示できるようにします。これらのドキュメントへの相対リンクは、.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 にサンプルのリポジトリをセットアップします。これには プロジェクトページはここにあります 、これがどのように連携するかを確認したい場合。

37
Cory Gross

READMEをGithubページと同期する問題に対する私の解決策は、上記とは少し異なります。別のJavaScript Markdownエンジンを使用する代わりに、Github APIを使用して、次のようにレンダリングされたMarkdownファイルを返すことができます。 HTML。

  1. _README.md_から_https://api.github.com/repos/<owner>/<repo>/contents/README.md_をフェッチします。
  2. Base64応答をデコードします：window.atob( JSON.parse( blob ).content );

  3. デコードされたREADMEをJSON本文で_https://api.github.com/markdown_に投稿する

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

  4. Brad Rhodes のように、レンダリングされたHTMLをDOM要素に挿入します。

このアプローチには2つの注意点があります。

  1. 2つのシリアル要求を実行すると、ページの読み込みが遅くなります。
  2. Github APIにアクセスするときにレート制限が発生する可能性があります。

読み込み時間が重要ではない（約1〜2秒）トラフィックの少ないページでは、上記の方法で十分に機能します。

5
kgryte

DocumentUp を使用して、README.mdをレンダリングできます。

4
niutech

ドキュメントサイトとメインのgithubリポジトリ間で単一のreadmeファイルを共有するためのアイデアがいくつかあります。

  1. コードとjekyllドキュメンテーションサイトの両方を含む単一のgh-pagesブランチのみを使用できます。リポジトリが少し乱雑になる可能性があるため、Readmeの上部にYAMLヘッダーを配置する必要があります。それalmostは相対リンクをサポートします。問題は、jekyllでマークダウンをレンダリングしたい場合に.html拡張子を付けることです。多分これを設定する方法があります。 これが動作するかどうか確認するために一緒に投げた例です

  2. ドキュメントサイトでAJAX呼び出しを使用してメインブランチからreadmeを読み取り、 Javascript Markdownレンダラー でレンダリングすることができます。これにはロードに少し時間がかかりますまた、巧妙なJavascriptを書かないと、相対リンクはサポートされません。また、アイデア1よりも実装が面倒です。

3
Nathan Breit

考慮すべき別のルートは、関連ページを構築する pre-commitフック を設定することです。 私のリポジトリの1つ でこれを行います。おそらく、自動ページジェネレーターを破棄し、gh-pagesブランチに自分でプッシュするだけでなく、ドキュメントをHTMLまたはJekyllサイトに変換するために特別なことを行う必要があります Nathanの提案 。

そのリポジトリでは I Push this thisgh-pagesをmasterと同一に保つため。それを行うには 他の方法 もたくさんあります。ただし、これは状況によっては理想的ではない場合があります（これらを同一にしたくない場合があります）。

とにかく、私がこの質問に賞金を提供した理由は、誰かがより良いワークフローを持っていることを望んでいたからです。この方法は、複雑で柔軟性に欠けるため、フックを同期させる必要があります。

3
Matt Kantor

NathanとBrand Rhodesによって説明された方法の別の可能性は、素晴らしいツールを使用することです： FlatDoc Rico Staによって作成されました。クルス。

FlatDocはajaxによってドキュメント（README.mdまたはその他のマークダウンファイル）をロードし、それを解析して、すべての便利な機能とナビゲーション用のサイドバーメニューを表示します。

Apiには、GitHubレポマスターからファイルを読み込むヘルパーメソッドが組み込まれています（ただし、Webから他の場所に読み込むこともできます）。

指示

まず、次の htmlテンプレート をgh-pagesブランチのindex.htmlにコピーします。続ける：

  • 「USER」をGitHubユーザー名に置き換えます
  • 「REPO」をGitHubリポジトリ名に置き換える
  • 「Your Project」をプロジェクト名に置き換えます

ファイル内。ブラウザでローカルに試してください。次に、変更をコミットしてプッシュします。これで、githubページは常にmasterブランチのREADME.mdファイルで更新されます。

デフォルトのテーマで満足できない場合は、独自のCSSでスタイルを変更できます。

2
Khalid Salomão

私がかなりうまく機能するようになったもう1つの方法は、Ajaxを使用して、Github APIとJavascriptマークダウンエンジンを使用してドキュメントをフェッチし、HTMLをレンダリングすることです（これもNathanによって提案されています）。

  1. Github APIとJSONPを使用してGithubからドキュメントを取得する
  2. Github APIからの応答のbase64コンテンツをデコードします
  3. JavaScriptマークダウンエンジンを使用してマークダウンをレンダリングする
  4. レンダリングされたHTMLを表示する

ネイサンはパフォーマンスについて懸念を表明しましたが、私の経験では、それは一見一瞬でロードされるため、実際には問題ではないと思います。

利点は、セットアップが簡単で、githubのブラウザーでマークダウンを直接編集した場合でも、常にドキュメントが更新されることです。

http://bradrhodes.github.io/GithubDocSync/ のGithubページに例を設定して、動作することを示しています。

2
Brad Rhodes

また、マスターでドキュメントを編集してgh-pagesで公開したいのですが、ソースコードを使用してドキュメントを最新の状態に保ち、それが最善の方法のようです。これは私にとって進行中の作業ですが、私は Cory's script を出発点として少し拡張し、__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
      }
    }
}
_

オリジナルからのもう1つのバリエーションは、すべてのページで変数_page.home_を設定することです。これは、ルートディクトリカルの相対パスを見つけるために使用できるため、CSSなどの静的リソースを見つけるために使用できます。 __layouts/.default.html_では、

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

このようにして、CSSを編集してjekyllサイトをローカルで構築し、githubがサーバーで構築するのを待たずにブラウザーで結果を確認できます。

1
Dave Syer

難しくはありません、2つのコピーとターミナルへの貼り付けが完了しました。

Jekyllを使用すると、マークダウンファイルをインポートして、HTMLに変換することができます。コツは、README.mdをindex.mdを使用して{% include_relative README.md %}ファイルにインポートすることです。以下にその方法を示します。

チェックアウトする価値があります GithubでスーパーベアボーンJekyllサイトをセットアップする方法 （それは2つのファイルです！ ）

セットアップ

これを実行するだけで、2つのファイルをコピーして現在のreadmeでページを処理できますワンタイムセットアップ（コピーコードブロック全体をターミナルに挿入します）：

# 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

gh-pagesを実行するたびに、masterブランチからgit Pushにすべての変更をコピーするプッシュフックが作成されます。

以上です。完了しました。

0
Marcelo Lazaroni

私は最近、この問題を解決するためにパッケージ gh-pages-generator を作成しました-複数のMDファイルと設定ファイルを使用してマルチページサイトを生成します。

ページ間のすべてのリンクを正しく更新します。変更をgh-pagesブランチにコミットすることをCIの一部にすることは比較的簡単です。

私はそれを使用しています ここ および ここ 。

0
esp