GitHub - Pagesのソースを表示

== 概要 ==
GitHub Pagesは、GitHubリポジトリから直接Webサイトを公開できる静的サイトホスティングサービスである。<br>
HTML、CSS、JavaScriptで構成された静的ファイルをリポジトリに配置するだけで、インターネット上に公開されたWebサイトを無料で運営できる。<br>
<br>
GitHub Pagesで公開できるサイトは以下に示す2種類に分類される。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub Pagesのサイト種別一覧
|-
! 種別 !! 説明
|-
| ユーザ・組織サイト || <code><ユーザ名 または 組織名>.github.io</code> という名前のリポジトリから公開するサイト<br>アカウントごとに1つのみ作成できる。<br>公開URLは https://<ユーザ名 または 組織名>.github.io となる。
|-
| プロジェクトサイト || 既存のリポジトリから公開するサイト<br>1つのアカウントで複数作成できる。<br>公開URLは https://<オーナー名>.github.io/<リポジトリ名> となる。
|}
</center>
<br>
GitHub Pagesは、プロジェクトのドキュメント、個人ポートフォリオ、ブログ、ランディングページ等の幅広い用途で利用されている。<br>
<br><br>

== GitHub Pagesの作成 ==
==== ユーザ・組織サイト ====
ユーザサイトまたは組織サイトを作成するには、特定の命名規則に従ったリポジトリを作成する必要がある。<br>
<br>
リポジトリ名は <u><ユーザ名>.github.io</u> (個人アカウントの場合) または <u><組織名>.github.io</u> (組織の場合) とする。<br>
アカウントごとに作成できるユーザ・組織サイトは1つのみである。<br>
<br>
リポジトリを作成後、デフォルトブランチ (通常は <u>main</u>) のルートディレクトリに <u>index.html</u> ファイルを配置することにより、サイトが公開される。<br>
<br>
==== プロジェクトサイト ====
プロジェクトサイトは、既存のリポジトリに対してGitHub Pagesを有効化することで作成する。<br>
<br>
プロジェクトサイトの公開URLは https://<オーナー名>.github.io/<リポジトリ名> となる。<br>
<nowiki><オーナー名></nowiki> は、GitHubのユーザ名または組織名に対応する。<br>
<br>
==== 公開ソースの設定 ====
GitHub Pagesの公開ソースは、リポジトリの[Settings] - [Pages]から設定する。<br>
<br>
公開ソースには以下の2つの方式がある。<br>
<br>
* ブランチからの公開
*: 指定したブランチのルートディレクトリ (<u>/</u>) または <u>/docs</u> ディレクトリの内容を公開する。
*: 設定は [Settings] - [Pages] - [Branch]でブランチ名とディレクトリを選択して保存する。
* GitHub Actionsでの公開
*: カスタムワークフローを使用してビルド・デプロイを行う。
*: <u>actions/upload-pages-artifact</u> でアーティファクトをアップロードして、<u>actions/deploy-pages</u> でデプロイする。
*: ワークフローには <code>pages: write</code> および <code>id-token: write</code> の権限が必要である。
<br>
GitHub Actionsを使用したデプロイワークフローの基本構成を以下に示す。<br>
<br>
 <syntaxhighlight lang="yaml">
 name: Deploy GitHub Pages
 
 on:
    push:
       branches: ["main"]
 
 permissions:
    contents: read
    pages: write
    id-token: write
 
 jobs:
    build:
       runs-on: ubuntu-latest
       steps:
          - uses: actions/checkout@v4
          - name: Build
            run: |
               # ビルドコマンドをここに記述する
          - uses: actions/upload-pages-artifact@v3
            with:
               path: ./dist
 
    deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
       steps:
          - id: deployment
            uses: actions/deploy-pages@v4
 </syntaxhighlight>
<br><br>

== Jekyll ==
==== Jekyllとは ====
JekyllはRubyで実装された静的サイトジェネレータであり、GitHub Pagesに公式統合されている。<br>
MarkdownファイルをHTMLに変換して、Liquidテンプレートエンジンを使用してレイアウトやコンポーネントを管理する。<br>
<br>
ブランチからの公開を設定している場合、GitHub Pagesはリポジトリ内のファイルを自動的にJekyllでビルドする。<br>
<br>
<u>Jekyllを使用しない場合は、リポジトリのルートディレクトリに <u>.nojekyll</u> という空ファイルを配置することにより、Jekyllビルドを無効化できる。</u><br>
<br>
==== _config.yml ====
<u>_config.yml</u> ファイルは、Jekyllサイトの主要な設定ファイルである。<br>
リポジトリのルートディレクトリに配置する。<br>
<br>
主要な設定項目を以下に示す。<br>
<br>
 <syntaxhighlight lang="yaml">
 # サイトの基本情報
 title: サイトタイトル
 description: サイトの説明文
 url: "https://<username>.github.io"
 baseurl: ""   # プロジェクトサイトの場合は "/<repo>" を指定する
 
 # テーマの設定
 theme: minima
 
 # プラグインの設定
 plugins:
    - jekyll-feed
    - jekyll-sitemap
 
 # 除外ファイルの設定
 exclude:
    - Gemfile
    - Gemfile.lock
    - README.md
 
 # Markdownエンジンの設定
 markdown: kramdown
 </syntaxhighlight>
<br>
<u>GitHub Pagesが自動的に上書きする設定項目があることに注意する。</u><br>
<br>
<center>
{| class="wikitable"
|+ GitHub Pagesが強制する設定
! 設定項目 !! 強制される値 !! 説明
|-
| <code>lsi</code> || <u>false</u> || 関連記事リストの生成を無効化する。
|-
| <code>safe</code> || <u>true</u> || ホワイトリスト外のプラグインを無効化する。
|-
| <code>highlighter</code> || <u>rouge</u> || シンタックスハイライトにRougeを使用する。
|}
</center>
<br>
==== テーマ ====
JekyllテーマはサイトのデザインとレイアウトをまとめたRuby Gemパッケージである。<br>
<br>
テーマの適用方法には以下の2つがある。<br>
<br>
* Web UIからの設定
*: リポジトリの[Settings] - [Pages] - [Choose a theme]から選択する。
*: 選択すると <u>_config.yml</u> ファイル内に <code>theme:</code> が自動的に追加される。
* <u>_config.yml</u> での設定
*: GitHub Pagesがサポートするテーマは <code>theme: テーマ名</code> で指定する。
*: GitHubホスト外のテーマは <code>remote_theme: owner/theme-repo</code> で指定する。
<br>
テーマのカスタマイズはリポジトリ内に <u>_layouts</u> ディレクトリを作成し、テーマのレイアウトファイルを上書きすることで行う。<br>
<br>
独自のCSSを追加する場合は、<u>assets/css/style.scss</u> に記述する。<br>
<br>
==== コンテンツ作成 ====
Jekyllのコンテンツはページとポストの2種類に分類される。<br>
<br>
* ページ
*: 独立したコンテンツ (About、Contact等) を作成する時に使用する。
*: リポジトリのルート直下または任意のディレクトリに <u>.md</u> または <u>.html</u> ファイルとして配置する。
* ポスト
*: ブログ記事等の時系列コンテンツを作成する時に使用する。
*: <u>_posts/</u> ディレクトリに <u>YYYY-MM-DD-タイトル.md</u> という命名規則で配置する。
<br>
各コンテンツファイルの先頭には、YAMLフロントマターと呼ばれるYAML形式のメタデータブロックを記述する。<br>
<br>
 <syntaxhighlight lang="yaml">
 ---
 layout: post
 title: "記事タイトル"
 date: 2026-03-24 12:00:00 +0900
 categories: [カテゴリ1, カテゴリ2]
 permalink: /custom-url/
 ---
 
 ここからMarkdownでコンテンツを記述する。
 </syntaxhighlight>
<br>
下表に、YAMLフロントマターで指定できる主要な項目を示す。<br>
<br>
<center>
{| class="wikitable"
|+ Front Matterの主要項目
! 項目 !! 説明
|-
| <code>layout</code> || 使用するレイアウトテンプレート名 (例: <u>page</u>, <u>post</u>, <u>default</u>)
|-
| <code>title</code> || ページまたは記事のタイトル
|-
| <code>date</code> || 公開日時 (ポストのみ)
|-
| <code>categories</code> || カテゴリの配列
|-
| <code>permalink</code> || カスタムURL
|}
</center>
<br>
==== ローカルテスト ====
GitHub Pagesに公開する前に、ローカル環境でサイトを確認することを推奨する。<br>
<br>
ローカルテストには、Ruby 2.7以上とBundlerおよびJekyllが必要である。<br>
Ruby 3.0以上を使用している場合は、追加で <u>webrick</u> Gem のインストールが必要である。<br>
<br>
ローカルテストの手順を以下に示す。<br>
<br>
# リポジトリのルートディレクトリで依存Gemをインストールする。
#: <pre>bundle install</pre>
#: <br>
# Jekyll開発サーバを起動する。
#: <pre>bundle exec jekyll serve</pre>
#: <br>
# Ruby 3.0以上でwebrickエラーが発生した場合は、以下に示すコマンドを実行する。
#: <pre>bundle add webrick</pre>
<br>
Webブラウザから http://localhost:4000 にアクセスしてサイトを確認する。<br>
ファイルを変更すると自動的に再ビルドされる。<br>
<br><br>

== カスタムドメイン ==
==== DNSレコードの設定 ====
カスタムドメインをGitHub Pagesに設定するには、ドメインのDNS設定を変更する必要がある。<br>
<br>
ドメインの種類によって設定するDNSレコードが異なる。<br>
<br>
* Apexドメイン (例: <u>example.com</u>) の場合
*: ドメインのDNS設定に以下の4つのAレコードを追加する。
<br>
<center>
{| class="wikitable"
|+ GitHub Pages用 AレコードのIPアドレス
! タイプ !! 値
|-
| A || 185.199.108.153
|-
| A || 185.199.109.153
|-
| A || 185.199.110.153
|-
| A || 185.199.111.153
|}
</center>
<br>
IPv6に対応する場合は、上記に加えてAAAAレコードも追加する。<br>
<br>
* サブドメイン (例: <u>www.example.com</u>) の場合
*: ドメインのDNS設定にCNAMEレコードを追加し、<u><owner>.github.io</u> を指定する。
<br>
==== リポジトリでのドメイン設定 ====
DNSレコードの設定後、GitHubリポジトリ側でカスタムドメインを設定する。<br>
<br>
設定手順を以下に示す。<br>
<br>
# リポジトリの[Settings] - [Pages] - [Custom domain]フィールドにカスタムドメインを入力する。
# [Save]ボタンを押下して保存する。
# リポジトリのルートディレクトリに <u>CNAME</u> ファイルが自動的に作成され、カスタムドメインが記載される。
<br>
<u>CNAME</u> ファイルはファイル名を大文字で記述して、ファイル内にはドメイン名を1行で記載する。<br>
<br>
==== HTTPS ====
GitHub Pagesではカスタムドメインに対してHTTPSを強制できる。<br>
<br>
HTTPS証明書はLet's Encryptによって自動的に発行される。<br>
証明書の発行には最大1時間掛かる場合がある。<br>
<br>
HTTPS設定の手順を以下に示す。<br>
<br>
# カスタムドメインのDNS設定とリポジトリのドメイン設定が完了していることを確認する。
# [Settings] - [Pages] - [Enforce HTTPS]のチェックボックスを有効にする。
<br>
Let's Encrypt証明書の自動更新を確実に行うため、ドメインのCAAレコードに <u>letsencrypt.org</u> を許可する設定を追加することを推奨する。<br>
<br>
==== ドメイン検証 ====
GitHub Pagesのドメイン検証機能を使用すると、他のGitHubユーザが自分のカスタムドメインをGitHub Pagesに設定することを防止できる。<br>
<br>
ドメイン検証はGitHubアカウントの[Settings] - [Pages] - [Verified domains]から設定する。<br>
検証はDNSのTXTレコードに指定の値を追加することで完了する。<br>
<br><br>

== 静的サイトジェネレータ ==
==== Jekyll以外のジェネレータ ====
GitHub PagesはJekyll以外の静的サイトジェネレータにも対応している。<br>
GitHub Actionsを使用してカスタムビルドワークフローを設定することにより、任意のジェネレータを使用できる。<br>
<br>
下表に、主要な静的サイトジェネレータを示す。<br>
<br>
<center>
{| class="wikitable"
|+ 主要な静的サイトジェネレータ
! ジェネレータ !! 言語 !! 特徴
|-
| Hugo || Go || 高速なビルド速度<br>大規模サイトに適している。
|-
| Next.js || JavaScript (React) || Reactベースのフレームワーク<br>SSG (静的サイト生成) モードで使用する。
|-
| Gatsby || JavaScript (React) || Reactベースの静的サイトジェネレータ<br>GraphQLによるデータ取得が特徴。
|-
| Nuxt || JavaScript (Vue.js) || Vue.jsベースのフレームワーク<br>SSG (静的サイト生成) モードで使用する。
|-
| MkDocs || Python || Markdownベースのドキュメントサイト生成に特化している。
|-
| Sphinx || Python || Pythonプロジェクトのドキュメント生成に広く使用されている。
|-
| Eleventy (11ty) || JavaScript || シンプルで柔軟な静的サイトジェネレータ
|}
</center>
<br>
==== GitHub Actionsでのカスタムビルド ====
GitHub Actionsを使用したカスタムビルドワークフローの主要なアクションを以下に示す。<br>
<br>
* <code>actions/upload-pages-artifact</code>
*: ビルド済みの静的ファイルをGitHub Pages用のアーティファクトとしてアップロードする。
*: <code>path</code> パラメータで公開するディレクトリを指定する。
* <code>actions/deploy-pages</code>
*: アップロードされたアーティファクトをGitHub Pagesにデプロイする。
*: デプロイされたページのURLが出力パラメータ <code>page_url</code> として返される。
<br>
Hugoを使用したデプロイワークフローの例を以下に示す。<br>
<br>
 <syntaxhighlight lang="yaml">
 name: Deploy Hugo Site
 
 on:
    push:
       branches: ["main"]
 
 permissions:
    contents: read
    pages: write
    id-token: write
 
 jobs:
    build:
       runs-on: ubuntu-latest
       steps:
          - uses: actions/checkout@v4
            with:
               submodules: true
          - name: Setup Hugo
            uses: peaceiris/actions-hugo@v3
            with:
               hugo-version: "latest"
          - name: Build
            run: hugo --minify
          - uses: actions/upload-pages-artifact@v3
            with:
               path: ./public
 
    deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
       steps:
          - id: deployment
            uses: actions/deploy-pages@v4
 </syntaxhighlight>
<br><br>

== 制限事項 ==
==== 技術的な制限 ====
GitHub Pagesを使用する時は、以下に示す技術的な制限に注意が必要である。<br>
<br>
<center>
{| class="wikitable"
|+ GitHub Pagesの技術的な制限
! 項目 !! 制限値 !! 備考
|-
| リポジトリサイズ || 1[GB]推奨 || ソースリポジトリのサイズ上限の目安
|-
| 公開サイトのサイズ || 1[GB]以下 || デプロイされるサイトの合計サイズ
|-
| 帯域幅 || 100[GB] / 月 || 月間のデータ転送量上限
|-
| ビルド時間 || 10分 || Jekyll または カスタムビルドの実行時間上限
|-
| アーティファクトサイズ || 10[GB] || GitHub Actionsアーティファクトのサイズ上限
|}
</center>
<br>
==== 禁止されている用途 ====
GitHub Pagesは静的サイトホスティングサービスであり、以下に示す用途での使用は禁止されている。<br>
<br>
* オンラインビジネス、eコマースサイト、商業目的のトランザクション処理を主目的とするサイト
* サーバサイドの処理が必要なWebアプリケーション (データベース接続、サーバサイドスクリプトの実行等)
* パスワードのクラッキング、ネットワーク攻撃等の不正行為に使用するサイト
* GitHubのサービス利用規約に違反するコンテンツの公開
<br>
GitHub PagesはGitHubの利用規約に従って運営されており、上記の禁止事項に違反した場合はサービスが停止される場合がある。<br>
<br><br>

== トラブルシューティング ==
==== Jekyllビルドエラー ====
Jekyllビルドで発生しやすいエラーとその対処法を以下に示す。<br>
<br>
* <code>_config.yml</code> 構文エラー
*: YAMLファイルにタブ文字を使用している場合はスペースに置き換える。
*: ファイルの文字エンコーディングがUTF-8であることを確認する。
*: コロン (<code>:</code>) の後には必ずスペースを入れる。
*: 文字列にコロンが含まれる場合は引用符で囲む。
* 非対応プラグインエラー
*: GitHub Pagesはセキュリティ上の理由から使用できるJekyllプラグインを制限している。
*: 使用できるプラグインは公式ドキュメントで確認する。
*: 非対応プラグインを使用する場合は、GitHub Actionsでのカスタムビルドに切り替える。
* Ruby 3.0以上での <code>webrick</code> エラー
*: <code>bundle add webrick</code> を実行して、<code>webrick</code> Gemを追加する。
<br>
==== カスタムドメインの問題 ====
カスタムドメイン設定で発生しやすい問題とその対処法を以下に示す。<br>
<br>
* DNS設定が反映されない。
*: DNS設定の変更が反映されるまで最大24時間かかる場合がある。
*: <code>dig</code> コマンド や [https://www.whatsmydns.net/ whatsmydns.net] 等のツールでDNS伝播状況を確認する。
* <code>CNAME</code> ファイルの形式エラー
*: ファイル名は大文字の <u>CNAME</u> とする。
*: ファイル内にはカスタムドメインを1行のみ記載する。
*: 余分な空行や文字が含まれていないことを確認する。
* HTTPS設定が有効にならない
*: Enforce HTTPSは、DNS設定が正しく完了してから有効にする。
*: 証明書の発行には最大1時間掛かる場合がある。
*: DNS設定後に1度カスタムドメインを削除して再設定すると解決することがある。
<br><br>


{{#seo:
|title={{PAGENAME}} : Exploring Electronics and SUSE Linux | MochiuWiki
|keywords=MochiuWiki,Mochiu,Wiki,Mochiu Wiki,Electric Circuit,Electric,pcb,Mathematics,AVR,TI,STMicro,AVR,ATmega,MSP430,STM,Arduino,Xilinx,FPGA,Verilog,HDL,PinePhone,Pine Phone,Raspberry,Raspberry Pi,C,C++,C#,Qt,Qml,MFC,Shell,Bash,Zsh,Fish,SUSE,SLE,Suse Enterprise,Suse Linux,openSUSE,open SUSE,Leap,Linux,uCLnux,電気回路,電子回路,基板,プリント基板
|description={{PAGENAME}} - 電子回路とSUSE Linuxに関する情報 | This page is {{PAGENAME}} in our wiki about electronic circuits and SUSE Linux
|image=/resources/assets/MochiuLogo_Single_Blue.png
}}

__FORCETOC__
[[カテゴリ:Git]]