Steps to publish a self-introduction page on GitHub Pages using Poetry and MkDocs#

This is a practical memo that organizes the steps to create a simple static page using MkDocs and publish it to GitHub Pages while managing packages with Poetry.

background #

We chose MkDocs as an easy way to publish your personal profile. In addition, I decided to use Poetry to explicitly manage dependencies.

Steps to create a static site with Poetry + MkDocs #

It proceeded as follows.

Project directory creation and initialization:

mkdir my-profile
cd my-profile
poetry init --name "my-profile" -n
poetry add mkdocs

Create document directory:

mkdir docs
echo "# 自己紹介ページ" > docs/index.md

Edit docs/index.md as follows:

# 自己紹介

こんにちは、名無しの権兵衛 です。

- 所属: ○○会社のエンジニア
- 興味: Python / Vim / ドキュメント管理
- 趣味: 宇宙や歴史の考察

mkdocs.yml creation:

site_name: 名無しの権兵衛 の自己紹介
theme:
  name: material

※ material テーマを使う場合は `poetry add mkdocs-material` も実行。

Check locally:

poetry run mkdocs serve

ブラウザで http://localhost:8000 を開く。

Integration and publishing with GitHub repositories #

Create a repository (e.g. my-profile) on GitHub and initialize it:

git init
git add .
git commit -m "initial commit"
git remote add origin https://github.com/<ユーザー名>/my-profile.git
git push -u origin master


※ ssh 接続を使用する場合は、以下のようにリモートURLを設定します。

   git remote set-url origin git remote set-url origin git@github.com:<ユーザー名>/my-profile.git

Deploy to GitHub Pages:

poetry run mkdocs gh-deploy
自動的に `gh-pages` ブランチが作成され、GitHub Pages から公開される。
公開URL: https://<ユーザー名>.github.io/my-profile/
GitHub Pages の設定は、リポジトリの Settings > Pages で確認できます。