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にフォルダの区分は / (スラッシュ)を用いる
      • 相対パス記述のルール
        • 現在の位置 = . (ピリオド)→ 現在のフォルダ ./
        • 一つ上の位置 = ..(ピリオド2つ)→ 一つ上のフォルダ ../

mkdocs.yml

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

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

テーマ変更