こんにちは、最近ブログの更新をわりと多めに頑張っています。といってもまだまだ数は少ないですが、これからも日々細かなナレッジを更新していこうと思います。
今日は普段はWordpress でブログを作ったり、他のPowerCMS やその他のSass を使うことが多いと思います。チケット管理とかだったら、redmine とかですかね。でももうちょっと完結になったらいいなとか思いませんか？？？
そこでMkdocs おすすめしたいなと思います。複数人で管理もしやすそう(大人数では管理はお勧めしないですが)なので、今日はその開発環境作成から、S3 デプロイまでのプロセスをかいていきます。(ドメインはつけないので) ゴールはS3 のURL をたたく所までですね！
WSL2 でmkdocs を使えるように
これはとても簡単です。
sudo apt install mkdocspython のpip でもインストールできるようですので、この方針でやりたい方はこの記事を参照してみてください。
https://docs.refrainit.com/mkdocs/install/
そして、プロジェクトを作っていくので、適当にディレクトリを作ってもらって、そこでmkdocs のコマンドを叩いていきます。
mkdir mywork
cd mywork
# mkdocs を作成
mkdocs new my-knowledge
#作成したディレクトリ移動
cd my-knowledge
#ディレクトリ構造
.
├── docs
│ │
│ └── index.md
└── mkdocs.yml上のようなディレクトリが初期構成になっていると思います。これで完成です！！
mkdocs を立ち上げてみる
これもnode 使っていたり、laravel 使っている方にもお馴染みのコマンドです。http://127.0.0.1:8000/ にアクセスして表示ができていると問題なく起動できています
mkdocs serve
127.0.0.1結構シンプルなサイト表示ですが、カスタマイズできるようになっているようですので、もしこういうのが好きな方はカスタマイズしてみてもいいかもしれません。もうすでにサイトとして成り立つような構造にもなっているので、そのままサイトとしても十分に使えるような完成度になっています。
https://www.mkdocs.org/user-guide/
ちなみに私はこんな感じでredmine みたいな形がよきでしたので、これに変更しています。
定義自体はmkdocs コマンドでプロジェクトを作ったときに mkdocs.yml が生成されていると思うのですが、そこで定義することで自動で変わります。なんて簡単なんだ。。。。。
ちなみにこんな感じです。まだまだ初心者なので、このレベルしかわかりません。
site_name: My Docs
theme:
name: readthedocs
locale: en
highlightjs: trueサイドバーに何か追加したいなーって思った時は、至極簡単でして、Markdown ファイルをどうディレクトリで作成したり、ディレクトリを作成したりするとその名前を読み取ってくれて、勝手にサイドバーにも反映されています。
S3 にデプロイしてみよう
今回デプロイするにあたって、普段からgitlab で管理していた事情もあり、S3 にもgitlab からデプロイしていきます。前提として、gitlab レポジトリが作成されていることと、aws のaccess key とsecret key も必要になりますので、それも準備が必要です。
事前にこの記事を参考にして、gitlab にAWSへのシークレットキーを登録してみてください。
https://blogs.networld.co.jp/entry/2022/10/10/090000
そして、gitlab からデプロイするためには、.gitlab-ci.yml が必要になります。なので、こんな感じで書いてあげたら大丈夫かと思います。ポイントは、cache の設定をしてあげることです。cache の設定でbuild したディレクトリを指定しなかったら、そのままデストロイされちゃうので、build の結果も残らないようになっています。(これで結構沼にハマりました….)
stages:
- build
- deploy
build:
stage: build
cache:
paths:
- ./site
script:
- apt update -y
- apt -y install mkdocs
- echo "start building mkdocs"
- mkdocs build
deploy:
stage: deploy
cache:
paths:
- ./site
variables:
AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
image: registry.gitlab.com/gitlab-org/cloud-deploy/aws-base:latest
script:
- echo "s3 deploy"
- echo "start deploying mkdocs"
- aws s3 sync site/ s3://<your-bucket-name>/そして、S3 側でも、ブロックパブリックアクセスを「オフ」にしてあげて、policy でget を有効化することを忘れないでください。後は、ホスティングの有効化してあげたら、サイトが閲覧できると思います。ちなみに、policy の設定はこんな感じです。
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PublicReadGetObject",
"Effect": "Allow",
"Principal": "*",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::バケット名/*"
]
}
]
}まとめ
今回はmkdocs をデプロイまでやってみました。今回はデプロイにGitlab を使いましたが、AWS であれば、code 系統のサービスを使ったり、そのままS3 のsync をCLI で使ってもいいかもしれませんね。その場合はローカルから実行することは前提として必要にはなりますが。。。
興味のある方はぜひデプロイとかも色々やってみてください！！！ではでは！次はCircle CI とかも使ってみようかな？？Terraform で定義できたらもっと楽かもとか思ったり。。。
コメント