このプロジェクトを非推奨にした理由の詳細については、こちらをご覧ください。
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 : true
requirements.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 に十分慣れている場合にのみカスタマイズすることをお勧めします。
トラブルシューティングガイドを参照してください。