fastpages
vements to styling
このプロジェクトを非推奨にした理由の詳細については、こちらをご覧ください。
fastpagesへようこそJupyter ノートブック、Word ドキュメント、Markdown をサポートする、使いやすいブログ プラットフォームです。
fastpages 、GitHub Actions を使用して、さまざまな入力形式から GitHub Pages で Jekyll ブログ投稿を作成するプロセスを簡素化します。
fastpages次の機能を提供します。機能の詳細なリストについては、以下を参照してください。
デモサイトを見る
fastpagesへようこそfastpages次の機能を提供します。このリンクをクリックして、このリポジトリのコピーを生成します。必ずアカウントにサインインしてください。サインインしないと、404 エラーが表示されます。リポジトリに、{your-username}.github.io以外の任意の名前を付けます。
GitHub Actions は、コピーが作成されてから約 30 秒後に、新しいリポジトリで PR を自動的に開きます。続行するには、その PR の指示に従ってください。
PR が表示されない場合は、組織でサードパーティのアクションが有効になっていることを確認してください: [設定] -> [アクション] -> [アクションの権限] -> [このリポジトリのローカルおよびサードパーティのアクションを有効にする]
セットアップ手順のライブ ウォークスルー (追加のヒントを含む) については、Abdul Majed による fastpages ブログのセットアップに関するこのビデオ チュートリアルを参照してください。
Read and Write権限を付与し、 Allow GitHub Actions to create and approve pull requestsをオンにします。 
権限を付与したら、リポジトリのホームページの上部にある「 Actionsタブに移動すると、実行されたアクションのリストが表示されます。まず、失敗した実行 (赤い X が付いた項目) をクリックします。
画面が表示され、右上にジョブを再実行できるボタンがあります。
これを実行すると、プル リクエストが表示されるはずです。
_posts 、 _notebooks 、または_wordディレクトリにコンテンツを追加します。このリポジトリでは、これらのフォルダー内のコンテンツの例に従って、コンテンツを構造化する方法を確認できます。注意すべき最も重要なことは前付です。これについては以下で詳しく説明します。さらに、ブログのナビゲーションバーに表示される追加のページを_pagesディレクトリに追加できます。 _wordディレクトリ内のコンテンツは前付をサポートしていないことに注意してください。 フロントマターを使用すると、ブログ投稿ごとにさまざまなオプションのオン/オフを切り替えたり、メタデータを fastpage のさまざまな機能に渡すことができます。
ノートブックでは、前付はノートブックの先頭にあるマークダウン セルとして定義され、次の内容が含まれます。
# "Title"
> "Awesome summary"
- toc: false
- branch: master
- badges: true
- comments: true
- categories: [ fastpages, jupyter ]
- image: images/some_folder/your_image.png
- hide: false
- search_exclude: true
- metadata_key1: metadata_value1
- metadata_key2: metadata_value2同様に、マークダウンドキュメントでは、同じ前付けがドキュメントの冒頭で次のように定義されます。
---
title : " My Title "
description : " Awesome description "
layout : post
toc : false
comments : true
image : images/some_folder/your_image.png
hide : false
search_exclude : true
categories : [fastpages, jupyter]
metadata_key1 : metadata_value1
metadata_key2 : metadata_value2
---追加のメタデータはオプションであり、カスタムの前付を設定できます。
前付で定義されるものはすべて有効な YAML である必要があることに注意してください。有効な YAML を提供しないと、ブログでページがレンダリングされない可能性があります。たとえば、タイトルにコロンを入れたい場合は、次のように二重引用符でコロンをエスケープする必要があります。
- title: "Deep learning: A tutorial"
詳細については、YAML に関するこのチュートリアルを参照してください。
Title希望のタイトルに置き換え、 Awesome summaryを希望の概要に置き換えます。注: YAML パーサーを破壊する可能性のあるコロンやその他の文字をエスケープできるように、これらの値を二重引用符で囲むことをお勧めします。
fast_templateマークダウン ヘッダーに基づいて目次を自動的に生成します。 toc:をtrueまたはfalseに設定することで、この機能のオンとオフを切り替えることができます。このオプションはノートブックでのみ機能します
branchフィールドは、ブログ投稿内でノートブックから Colab および GitHub へのリンクをオプションでレンダリングするために使用されます。ノートブックで指定しない場合、デフォルトでmasterになります。badges falseに設定します。これのデフォルトはtrueですbadges: true設定すると、 4 つのバッジ (GitHub、Binder、Deepnote、Colab) がすべて表示されます。これらのデフォルトは、サイト全体の構成オプションのdefault_badgesパラメータを使用して調整できます。個々の投稿のバッジのみを非表示にしたい場合は、前付hide_{github,colab,binder,deepnote}_badge: true設定できます。たとえば、個々のノートブックのバインダー バッジを非表示にし、他のバッジは表示したい場合は、前付でこれを設定できます。
- badges : true
- hide_binder_badge : truerequirements.txtファイルをリポジトリのルートに追加することです。詳細については、Binderの公式ドキュメントを参照してください。ブログ投稿のカテゴリの角括弧内にカンマ区切りのリストを含めることができます。これにより、その投稿がブログ サイトのタグ ページに表示されます。例えば：
ノートの場合:
# "My Title"
- categories: [fastpages, jupyter]
マークダウンドキュメント内:
---
title: "My Title"
categories: [fastpages, jupyter]
---
これがどのようになるかのプレビューをここで見ることができます。
_config.ymlでshow_tags trueまたはfalseに設定することで、タグの表示のオン/オフを切り替えることができます。 # Set this to true to display tags on each post
show_tags : trueブログ投稿へのコメントは、オープンソースで広告なしのコメント実装方法である Utterances を利用しています。すべてのコメントは、ブログの GitHub リポジトリの Issue に保存されます。 comments trueに設定すると、これをオンにすることができます。これのデフォルトはfalseです。
発話付きのコメントを有効にするには、次の操作を行う必要があります。
Twitter などのソーシャル メディア サイトでは、URL とともに画像のプレビューを自動的に表示できます。前付image指定すると、このメタデータがソーシャル メディア サイトに提供され、この画像がレンダリングされます。この値は次のように設定できます。
- image: images/diagram.png
注: この設定では、リポジトリの/imagesフォルダー内のイメージ ファイルとフォルダーのみを参照できます。
ブログ投稿がホームページにリストされるのを防ぎたい場合でも、目立たずにプレビューまたは共有できる公開 URL を保持したい場合があります。前付の非hide trueに設定すると、ホームページからブログ投稿を非表示にできます。これはデフォルトではfalseに設定されています。
非表示のブログ投稿に対する予測可能な URL を生成するには、パーマリンクを使用することをお勧めします。ユーザーが検索で非表示の投稿を見つけたくない場合は、前付のsearch_exclude trueに設定することもできます。
デフォルトでは、ホームページ上の投稿は日付順に並べ替えられます。ただし、1 つ以上のブログ投稿を常にホームページの最上部に表示したい場合があります。言い換えれば、特定の投稿を「固定」または「固定」したい場合があります。これを実現するには、スティッキー投稿を表示したい順序でsticky_rank前付を指定します。このパラメータを設定しないブログ投稿は、デフォルトの方法でスティッキー投稿の後に日付順に並べ替えられます。
たとえば、次の 3 つのマークダウン投稿について考えてみましょう (ノートブックにも適用できます)。
2020-01-01-Post-One.md
---
title : Post One
sticky_rank : 1
--- 2020-02-01-Post-Two.md
---
title : Post Two
sticky_rank : 2
--- 2020-04-01-Post-Three.md
---
title : Post Three
---ただし、 sticky_rankが指定されているため、ブログ投稿は最初に Sticky_rank によって昇順に並べ替えられ、次に日付によって降順に並べ替えられるため、これらの投稿の順序は次のようになります。
sticky_rankがないと、各投稿に関連付けられた日付により、上記の投稿は実際には逆順に並べ替えられます。
注: ピン留めはノートブックでも機能します。
# "My cool blog post"
> "Description of blog post"
- sticky_rank: 2
fastpages には、lunr.js を利用したキーワード検索が組み込まれています。前付のsearch_exclude falseに設定すると、ブログ投稿またはページが検索結果に表示されないようにすることができます。これはデフォルトでtrueに設定されています。
全員がサイト全体の構成オプションを設定して、ブログ サイトをパーソナライズすることをお勧めします。これらのオプションは/_config.ymlにあります。以下に、利用可能なさまざまなオプションについて説明します。
title : これは、すべてのページのヘッダーの左上隅に表示されるタイトルです。
description : この説明は、サイトのプレビューが生成されるときにさまざまな場所 (ソーシャル メディアなど) に表示されます。
github_username : これにより、サイトのフッターに GitHub ページへのリンクを表示できるようになります。
github_repo : これにより、サイトで GitHub、Colab、ノートブック用 Deepnote へのリンクなど、さまざまな機能のリポジトリへのリンクをレンダリングできるようになります。
url : カスタム ドメインがない限り、これを変更する必要はありません。注: この値の末尾の / は省略します。
baseurl : この値を適切に設定する手順については、 /_config.ymlのコメントを参照してください (「baseurl の特別な手順」。カスタム ドメインがない場合は、このオプションを無視してかまいません。
email : 現在使用されていません。無視する。
twitter_username : フッターに twitter ページへのリンクを作成します。
use_math : LaTeX 数式のサポートを取得するには、これをtrueに設定します。これは、使用できない各ページに JavaScript を読み込むため、デフォルトではオフになっています。
show_description : ブログ投稿のリストを含むホームページ上のブログ投稿のタイトルの下に説明が表示されます。デフォルトではtrueに設定されます。
google_analytics : 必要に応じて、追跡に Google Analytics ID を使用します。
show_image : true に設定すると、ブログ投稿の前付けのimageパラメーターを使用して、以下に示すようにブログのプレビューが表示されます。これはデフォルトではfalseに設定されています。 show_image がtrueに設定されている場合、ホームページは次のようになります。
show_tags : この値をfalseに設定すると、ブログ投稿のタグの表示のオンとオフを切り替えることができます。これはデフォルトでtrueに設定されており、ブログ投稿のタグに対して次のリンクが次のように表示されます。
pagination : これは、ホームページの各ページに表示される投稿の最大数です。この量を超える投稿は別のページに分割されます。これはデフォルトでは15に設定されています。これがトリガーされると、ホームページの下部に次のようにページネーションが表示されます。
注: 古いバージョンの fastpage を使用している場合、自動アップグレード プロセスを使用してページネーションを取得することはできません。代わりに、次の手順に従う必要があります。
mv インデックス.md インデックス.html
GemfileとGemfile.lockこのリポジトリ内のファイルに置き換えます。_config.yml次のように編集します (例については _config.yml を参照してください)。 gems :
- jekyll-paginate
paginate : 10
paginate_path : /page:num/あるいは、fastpages テンプレートから作成された新しく作成されたリポジトリにすべての投稿をコピーすることもできます。
default_badges : デフォルトでは、GitHub、Binder、Deepnote、Colab のバッジがノートブックのブログ投稿に表示されます。これらのデフォルトを調整するには、 default_badgesの適切な値を false に設定します。たとえば、デフォルトでバインダー バッジをオフにしたい場合は、 default_badges次のように変更します。
default_badges :
github : true
binder : false
deepnote : false
colab : true html_escape : これにより、ブログ投稿のさまざまなコンポーネントでの HTML のエスケープのオンとオフを切り替えることができます。現時点では、投稿のdescriptionフィールドでのみこれを切り替えることができます。
これはデフォルトではfalseに設定されています。
/_sass/minima/custom-variables.scss を編集することで、さまざまなデバイス上の fastpages のページ幅を調整できます。
これらはデフォルト値であり、好みに合わせて調整できます。
// width of the content area
// can be set as "px" or "%"
$content-width : 1000 px ;
$on-palm : 800 px ;
$on-laptop : 1000 px ;
$on-medium : 1000 px ;
$on-large : 1200 px ;hypothes.is は、公開または非公開のページに注釈を付けたり強調表示したりする方法を提供するオープン プラットフォームです。この機能を有効にすると、ブログの読者にテキストを強調表示するときに次のツールチップが表示されます。
これは、fastpages ではデフォルトで無効になっています。 annotations trueまたはfalseに設定することで、_config.yml ファイルでこれを有効または無効にできます。
# Set this to true to turn on annotations with hypothes.is
annotations : falseこれらの構成オプションを読んで、hypothes.is をカスタマイズできます。また、hypothes.is についてさらに詳しく知りたい場合は、これらのドキュメントを読むことをお勧めします。ただし、この機能をカスタマイズする前に、「fastpages のカスタマイズ」セクションで重要な注意事項を読む必要があります。
RSS フィードを使用して読者に購読を促すことができます。インターネット上では、さまざまな RSS 購読サービスが提供されています。例としては次のようなものがあります。
fastpages Dracula テーマを使用して minima のデフォルトの構文強調表示をオーバーライドします。
fastpages のデフォルトの強調表示は次のようになります。
ただし、次のように選択すると、構文の強調表示を次のようにすることができます。
上記のライトテーマに戻したい場合は、_sass/minima/custom-styles.scss 内の以下の行を削除してください。
@import " minima/fastpages-dracula-highlight " ;これらのテーマのいずれも気に入らない場合は、独自の CSS を_sass/minima/custom-styles.scssに追加できます。詳細については、「fastpage のカスタマイズ」を参照してください。
このブログ投稿では、fastpage のダーク モードを有効にする方法について説明します。
引用システム BibTeX の使用を希望するユーザーは、そうすることができます。 jekyll-scholar プラグインを有効にする必要があります。これを実装する手順については、BibTeX および jekyll-scholar を介した Fastpages の引用を参照してください。
コードセルの先頭にコメント#hide配置すると、そのセルの入力と出力の両方が非表示になります。
セルの先頭にある#hide_inputコメントは入力のみを非表示にします。
さらに、 hide input Jupyter 拡張機能を使用してセルの入力または出力を非表示にすることができ、これは fastpages によって尊重されます。
コードをリーダーから完全に隠すのではなく、折りたたまれた要素内に一部のコードを隠し、ユーザーが展開できるようにしたい場合があります。
#collapseを配置します。#collapse_showまたは#collapse-showを配置します。#collapse_outputまたは#collapse-output配置します。ノートブックのマークダウン セルで、次のマークダウン ショートカットを使用して Twitter カードと YouTube ビデオを埋め込みます。
> youtube: https://youtu.be/your-link
> twitter: https://twitter.com/some-linkノートブックに脚注を追加するのは、マークダウンとは少し異なります。 「ノートブックの脚注の詳細ガイド」を参照してください。
命名規則YYYY-MM-DD-*.このリポジトリの/_notebooksフォルダーまたは/_wordフォルダーにそれぞれコピーします。たとえば2020-01-28-My-First-Post.ipynbです。 Jekyll がブログ投稿を表示するには、この命名規則が必要です。
ファイル名を正しく付けるように注意してください。 YYYY-MM-DD-の最後のダッシュを忘れがちです。さらに、ダッシュの直後にある文字はアルファベットのみである必要があります。有効なファイル名の例は次のとおりです。
2020-01-28-My-First-Post.ipynb
2012-09-12-how-to-write-a-blog.ipynbファイルに正しく名前を付けなかった場合、 fastpages生成されたブログ投稿の先頭にファイルの最終変更日を追加することで自動的に問題を解決しようとします。ただし、透明性を高めるために、自分でファイルに適切な名前を付けることをお勧めします。
ファイルをリポジトリのマスター ブランチの GitHub にコミットしてプッシュします。
GitHub はファイルを自動的にブログ投稿に変換します。変換プロセスが完了するまでに最大 5 分かかります。リポジトリの「アクション」タブをクリックすると、このプロセスのログを表示できます。 master ブランチにプッシュするたびにトリガーされる 2 つのワークフローがあります: (1) 「CI」と (2) 「GH ページ ステータス」。サイトが更新される前に、両方のワークフローが最新のコミットに緑色のチェックマークを付けて完了する必要があります。
必要に応じて、GitHub にコミットする前に、ブログがローカルでどのように表示されるかをプレビューできます。プレビューをローカルで実行するための詳細なガイドについては、このセクションを参照してください。
ブログ投稿をマークダウンで作成している場合は、ノートブックに指定されているのと同じ命名規則 ( YYYY-MM-DD-*.md ) を使用して、 .mdファイルを/_postsフォルダーに保存します。
Microsoft Word ドキュメントを、ノートブックに指定されているのと同じ命名規則 ( YYYY-MM-DD-*.docx ) を使用して/_wordフォルダーに保存します。
注: Word 文書の alt テキストは fastpages ではまだサポートされていないため、画像へのリンクが壊れます。
fastpages Word 文書の前付けを指定する確実な方法がありません。現時点では、_action_files/word_front_matter.txt を編集することによって、すべての Word 文書に対して前付をグローバルに指定することしかできません。
Word 文書ごとに固有の前付けを指定するには、Word を手動でマークダウン ファイルに変換する必要があります。このブログ投稿の手順に従って、Pandoc を使用して変換を行う方法を説明します。注: Word で生成されたブログ投稿をマークダウンでカスタマイズする場合は、マークダウン ファイルが上書きされないように、必ず _word ディレクトリから Word 文書を削除してください。
ブログ投稿の主な作成方法が Word ドキュメントであり、Word から変換されたマークダウン ファイルを常に手動で編集する予定がある場合は、fastpages の代わりに fast_template を使用する方がよいでしょう。
開発ガイドを参照してください。
fastpagesアクションを使用すると、リポジトリ内の/_notebooksのノートブックと/_wordディレクトリの Word ドキュメントを、 /_postsにある Jekyll 準拠のブログ投稿マークダウン ファイルに変換できます。注: このディレクトリ構造は Jekyll で使用するように設計されているため、現時点ではこのアクションに対して柔軟性がありません。
すでに Jekyll に十分慣れていて、この自動化を独自のテーマで使用したい場合は、次のようにfastai/fastpages@masterを参照して、この GitHub アクションを使用できます。
...
uses : fastai/fastpages@master
...完全なワークフローがどのようなものかを示す例は次のとおりです。
jobs :
build-site :
runs-on : ubuntu-latest
...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
...
- name : Jekyll build
uses : docker://jekyll/jekyll
with :
args : jekyll build
- name : Deploy
uses : peaceiris/actions-gh-pages@v3
if : github.event_name == 'push'
with :
deploy_key : ${{ secrets.SSH_DEPLOY_KEY }}
publish_branch : gh-pages
publish_dir : ./_siteこのアクションには必須の入力がなく、出力変数もないことに注意してください。
BOOL_SAVE_MARKDOWN : 「true」または「false」のいずれか。ノートブックおよび Word ドキュメントから変換されたマークダウン ファイルをリポジトリの _posts ディレクトリにコミットするかどうか。これはデバッグに役立ちます。デフォルト: falseSSH_DEPLOY_KEY : BOOL_SAVE_MARKDOWN = 'true' の場合、ssh デプロイ キーが必要ですaction.yml のこのアクションの API 仕様を参照してください。
このブログをカスタマイズする方法の詳細な手順は、この README の範囲を超えています。 (このリポジトリでこれを行う方法について、コミュニティの誰かがブログ投稿に寄稿するよう招待します。)
貢献ガイドをご覧ください。
アップグレードガイドを参照してください。
_posts/内のどこにありますか? A:このリポジトリの GitHub Actions ワークフローは、サイトを構築する前にノートブックと Word ドキュメントをその場でマークダウンに変換しますが、これらの中間マークダウン ファイルをこのリポジトリにコミットすることはありません。これは、ローカル環境がリポジトリと常に同期していないという煩わしさから解放されるためです。必要に応じて、次のように.github/workflows/ci.yamlファイルの fastpages アクションにBOOL_SAVE_MARKDOWNおよびSSH_DEPLOY_KEY入力を設定することで、これらの中間マークダウン ファイルを表示できます。 ...
- name : convert notebooks and word docs to posts
uses : fastai/fastpages@master
with :
BOOL_SAVE_MARKDOWN : true
SSH_DEPLOY_KEY : ${{ secrets.SSH_DEPLOY_KEY }}
... Q: Jekyll ドキュメント サイトや Jekyll ブログ投稿以外のものにfastpages使用できますか? A:現時点では、 fastpages 、Jekyll ブログ投稿に対してのみ機能する、非常に独自のソリューションです。 Jupyter ノートブックを使用してモジュールまたはライブラリのドキュメントを作成したい場合は、この目的のために明示的に構築された fastai/nbdev を使用することをお勧めします。
Q: fast_template と fastpages の違いは何ですか?どれを使えばいいのでしょうか？ A: fastpagesより柔軟で拡張性があるため、可能な場合は使用することをお勧めします。 fast_template 、技術的な専門知識がまったくなく、Github の統合オンライン エディターを使用して投稿のみを作成する人がブログを書く場合に適したオプションかもしれません。
fastpages は minima テーマに基づいて構築されています。 fastpage のスタイルやレイアウトをカスタマイズしたい場合は、minima の README に手順が記載されています。ディレクトリ構造を理解するには、README の全内容を読むことをお勧めします。さらに、テーマをカスタマイズする前に、Jekyll の基本を理解しておくことをお勧めします。 Jekyll を初めて使用する人は、公式ドキュメントから始めるのが良いでしょう。具体的には、 _sass/minima/custom-styles.scssの fastpages で css をオーバーライドできます。 minima の「スキン」機能は現在、fastpages の CSS 設定と互換性がないことに注意してください。
fastpages をカスタマイズすることを選択した場合、行ったカスタマイズが fastpages の現在または将来のバージョンと衝突する可能性があるため、HTML と CSS に十分慣れている場合にのみカスタマイズすることをお勧めします。
トラブルシューティングガイドを参照してください。
