今まで開発ドキュメントをまとめるのにGithubのWikiを使っていたが、別のツールを使いたい。
いままで
ちなみにWikiはローカルでmarkdownで書いて、プッシュする方式。画像もローカルのリポジトリに置いて、markdownにそのパスを書く方式
同じような感じでいいけどGithubのWikiではなくhtmlに変換して、最終的に一般の人にも公開できたり、お互いのページのリンクを貼ったりしたい。
記述方式はMarkdownでローカルで管理・移植できるといいので、ふつうのweb上のwikiサイトを使うのは違う
他社
vrmはgithub pages。ページ自体は何で書いているんだろう？
clusterはzendesk (Wikiというレベルではない）
MkDocs
ぴったり！
でも黒い画面を使う；；
とりあえずやってみる。完全に上の記事をなぞっているだけです。
pythonを入れる
MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3.
と書いてたので最新は3.9だけど一応3.8入れた
Python Release Python 3.8.6 | Python.org
インストーラーで入れた。pathにチェック入れるのを忘れずに！
まずはここから！Pythonのインストール方法【初心者向け】｜現役エンジニアが解説 | TechAcademyマガジン
mkdocsインストール
pip install mkdocs
でmkdocs入れる
中身作成
作りたいディレクトリに移動して、
mkdocs new XXX
でその名前のフォルダができる。中身も生成される
docsの中のindex.mdなどが中身のページになる。
ブラウザ確認
プロジェクトの中に移動して、mkdocs serveと書く
これでhttp://localhost:8000にアクセスすると
おおーできてる！
しかもローカルで変更したらすぐにwebに反映される！Ctrl+S押さなくても反映される。そんなことできるんだ～
htmlに書き出し
上のはローカルで、mdをhtmlに変換して表示してくれているみたいだけど、ちゃんとhtmlに書き出す
プロジェクトで、mkdocs build
これでhtmlが生成される。
デザイン変更
テンプレートをインストールして、mkdocs.ymlを変えると良いそうです。
インストール
pip install mkdocs-material
mkdocs.yml
ここでサイト名も変えられるのか
変わった！マテリアルデザイン
他のデザイン
その他の書き方はこちらが詳しかったです
GithubPagesへのアップ
書き出したhtmlをリポジトリ管理してGithubPagesとかで表示したらいいのか～
mdごと管理しつつそのリポジトリでGithubPagesにもしたい
https://bibinba.github.io/MkDocsTest/
htmlなどが入っているのはsiteフォルダのほう
なのにGithubPagesのSourceでなぜかdocsしか選べない。docsはmdファイルが入っているのに！
そういうものらしい。
今まではProject Pagesで公開するサイトのソースはgh-pagesという名のブランチに置く必要があったが、ソース設定によりmasterブランチのルートに置いたりmasterブランチの/docsフォルダに置いたりもできるようになった。
今回たまたまリポジトリ内にdocsフォルダがあったけど、もともとGithubPagesのソースは、ルートかdocsという名前のフォルダしか選べない
指定ディレクトリだけプッシュする方法などもある模様
コマンド
他の人はどうしているんだろうと思ったら、GithubPagesへのコマンドがMKDocs公式で用意されている！
mkdocs gh-deploy
これで gh-deployブランチができてそこにhtmlが置かれる。
・・・はずだけど失敗した。
gh-pagesブランチがGithub上にできてない。
ERROR - Failed to deploy to GitHub with error:
fatal: 'origin' does not appear to be a git repository
fatal: Could not read from remote repository.
SourceTreeでやってるから権利がないの？？？いろいろやったけどうまくいかなかった
GithubAction
GithubActionも組み合わせたら、mdをプッシュしたらhtmlも自動で更新される。
この方法使ったほうが良いかな～楽だし
こちらの方はhtmlとmdは別のリポジトリを使っている。
GithubActionの公式サンプルにMKDocsが載ってるんだね～そんな有名だったんだ。
GithubActionやったことない。別途やってみた。
失敗してた。
ここら辺をどう置き換えたらいいんだろう；；パッケージ管理なんてしてない
元のテンプレに一部置き換えたけど、ここで失敗してた
最後に
内輪向けに使う分にはWikiのほうが便利な気もするけど、デザイン性とか公開するときのことを考えたらこっちのほうが良いのかな～？
というか普段はWikiで書いておいて公開するときにこれを使えばいいのかな？
