Into the Program

【Setup】MkDocs

Image

MkDocsとは

Markdown記法で書けるドキュメント向けの静的なサイトジェネレータです。Bootstrapがベースとなっているため、Markdown記法で容易に見た目が整ったドキュメントベースのWebサイトを作ることができます。

Markdown記法というのは、文書を記述するための軽量マークアップ言語のことです。プレーンテキストで記述した文章をHTMLなどのマークアップ言語へ変換できる、汎用性が高い言語です。

MkDocsの公式サイトは以下の「Official Site」から確認できます。

Official Site

公式サイトはMkDocsで作成されていますので、作成したWebサイトがどんな見た目になるのか想像しやすいかと思います。

MkDocsの情報はインターネット上に溢れていますが、Windows環境にインストールする際に若干手間取ったため、導入手順を記録として残しておきたいと思います。導入が済めば後はスムーズに開発することができますので、本ページではMkDocsインストールから実行までを解説しております。

インストール

MkDocsはPythonという言語をサポートしているため、MkDocsをインストールするためにはPythonのパッケージ管理システムであるpipを実行できるようにしなくてはなりません。そのため、Pythonをインストールする必要があります。以下の「Downloads」からPythonのダウンロードページへ移動できます。

Downloads

リンク先に遷移すると以下の画面が表示されます。「Downloads」上にマウスカーソルを移動させるとOS名が縦に並んだリストが表示されますので、「Windows」の項目から赤線内のインストーラをダウンロードしてください。

mkdocs-001

ダウンロードしたPythonのインストーラを起動すると、「Python (Version) Setup」画面が表示されます。画面の下の方にある「Add Python (Version) to PATH」にチェックを入れ、「Install Now」を選択します。「Add Python (Version) to PATH」にチェックを入れることにより、Pythonへの環境変数が自動的に追加されます。

mkdocs-002

「Setup Progress」が表示され、インストールが開始されます。プログレスバーがいっぱいになるまでしばらく待ちます。

mkdocs-003

「Setup was successful」が表示されれば、Pythonのインストールは完了です。「Close」でインストーラを閉じます。「コントロールパネル > システムとセキュリティ > システム > システムの詳細設定 > 環境変数」にPythonへのPATHが2つ追加されていますので、確認しておきましょう。

Pythonのインストール後、「Windowsボタン + R」で「ファイル名を指定して実行」を開いて「cmd」と入力し、コマンドプロンプトを開きます。以下のコマンドを入力して、PythonへのPATHがきちんと通っているか確認しましょう。Python バージョンが表示されれば問題ありません。

python –version

Python 3.5.1

では早速MkDocsをインストールします。以下のコマンドを入力後、エンターキーで実行します。

pip install mkdocs

成功すると以下のようにダウンロードステータスが表示されます。最後に「Successfully installed ~」と表示されればインストールは無事成功です。

mkdocs-004

続いてMkDocsのドキュメントを格納するフォルダと新しいプロジェクトを作成します。以下の画像と同じようにコマンドを入力してみてください。

mkdocs-005

実行したコマンドの順に動作について記載しておきます。


//C:Users\Usernameに「mkdocs」フォルダ作成
mkdir mkdocs

//C:Users\Username\mkdocsへ移動
cd mkdocs

//C:Users\Username\mkdocsに「sample」プロジェクト作成
mkdocs new sample

//C:Users\Username\mkdocs\sampleへ移動
cd sample

//ローカル環境でプレビュー
mkdocs serve

//本記事では未使用。プレビューで問題なければHTMLへ出力
mkdocs build

上記コマンドがすべて実行されると「http://127.0.0.1:8000」というURLが表示されます。こちらにアクセスすると「sample」で作成中のドキュメントがローカルで確認できます。早速アクセスしてみましょう。

「http://127.0.0.1:8000」にアクセスするとサンプルページが表示されます。後はプロジェクトフォルダの配下にある「docs」内にドキュメントを追加していきましょう。各種設定はプロジェクトフォルダ直下の「mkdocs.yml」に追記します。終了する際はコマンドプロンプトを閉じます。

mkdocs-006

MkDocsの設定は以下の「User Guide」のページで解説してあります。全文英語ですが、わかりやすい内容になっていますので作成時に活用しましょう。

User Guide

最後に

筆者がよく使う装飾をご紹介したいと思います。

マークダウンで書いていますので、プロジェクトフォルダの「docs」配下にある「index.md」にコピーペーストしてどのように表示されるか見て頂ければ幸いです。

# 見出し
見出しはシャープを使って表します。

シャープの個数によって見出し文字の大きさを変更することができます。

# 段落
空白の行で囲まれた1行でひとつの段落になります。
改行後に1行以上の空白がなければひとつの段落と見なされますので注意しましょう。

# 強調
強調したい文言を2つのアスタリスクで囲みます。

**強調**

# 線
3つ以上のハイフンが連続した場合は線として扱われます。

---

# リンク
 [Test Hyperlink](ここにURLを記載する)

# リスト
リストはアスタリスク、ハイフン、プラスを入力してスペースかタブを挿入して作成します。

リストの途中で記号を変更することにより入れ子表示が可能です。

* JAVA
    - Javaについて
          + Java言語とは?
          + Java言語とは?
* PHP
    - PHPについて
* HTML
* SETUP

# テーブル

列①  | 列②  | 列③
---- | ---- | ----
内容 | 内容  | 内容
内容 | 内容  | 内容

# コード
先頭に半角スペースを4つ挿入して文言を記載することでコードを表します。

    <html>
      <head>
        <title>markdown test</title>
      </head>
      <body>
        <h1>よく使う装飾</h1>
        <p>私がMarkdownを書く際によく使う装飾をご紹介しています</p>
        <p>もっと詳しくしりたい方はMarkdownでググると幸せになれます。</p>
      </body>
    </html>

以上です。

SHARE

おすすめの書籍