Cheat Sheet for MkDocs#

MkDocsのチートシート

インストール

MkDocs のページを参考に

基本

docs フォルダの中身が実際のWebページとして生成される
設定ファイルは mkdocs.yml
- サイトタイトル、サイト構造（メニュー）、適用するデザインテンプレートの情報を記述する
.gitlab-ci.yml は repisitoryへpushした後にgitlab側で走らせる CI/CLの設定を書くファイル
- MkDocsを使う場合は特に変更しなで良い
- このファイルを消してしまうとCI/CLのプロセスが走らず、Webサイトに反映されないので気をつけること

まずは書いてみる

なんでもいいのでエディタを開いて、docsフォルダの中に week01.md というファイルを作成してみる。サンプルとして次のように打ち込んでみましょう。出来上がったら保存する。

# 1. Principals and Practices

## Assignment

- plan and sketch a potential final project

ローカル環境で確認する

mkdocs.yml ファイルがある場所で、以下のようにコマンドを入れます。

mkdocs serve

すると、起動しているターミナル上で以下のような表示になる。

yosuke@yosuke-ThinkPad-E490:~/repo/tsuchiya-yosuke$ mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - projects/final-project-masterpiece.md
  - projects/sample-project.md 
[I 200201 10:49:20 server:296] Serving on http://127.0.0.1:8000
[I 200201 10:49:20 handlers:62] Start watching changes
[I 200201 10:49:20 handlers:64] Start detecting changes

mkdocs のWebサイトが正しく表示されるかのテストを行うための仮想サーバーが立ち上がる。この状態で、ブラウザを起動してURLへアクセスしてみる。上記のテストで作ったページのURLは以下の通りとなる。

http://localhost:8000/week1/

そうすると、Markdownで書いたページを確認することができる。仮想サーバを止めるときはターミナルでCtrl+c を押す。

ファイルとフォルダの構造

サイトのトップページは docs 直下の index.md
docs 直下に week1.mdというファイルを作成すると、実際のWebページのURLは以下のとおりとなる

http://localhost:8080/week1/

たとえば各週の課題をdocs直下のassignmentsフォルダの中に集めて、その中に入れた場合は、URLは以下の通りとなる

http://localhost:8000/assignments/week1/

絶対パスと相対パス: 基本的にはModocsのMarkdownでは相対パスで記述する
- 絶対パス：http://~~ から始まる。URLを書く。
- 相対パス：htmlファイルの置かれているフォルダ（階層）を基準にしてフォルダ名、ファイル名を指定して、相対的に場所を特定し記述する。
  - HTMLにフォルダの区分は / （スラッシュ）を用いる
  - 相対パス記述のルール
    - 現在の位置　＝　. （ピリオド）→ 現在のフォルダ ./
    - 一つ上の位置＝　..（ピリオド２つ）→　一つ上のフォルダ ../

mkdocs.yml

mkdocs.yml でサイトの様々な設定を行うことができる。

site name: サイトの名前を書く。
site description: サイトの説明を書く。
theme: テーマ設定を記述する場所
nav: ページナビゲーションを記述する場所
- ここに記述した内容がサイトメニューに反映される

テーマ変更