Help us understand the problem. What is going on with this article?

ドキュメント作成ツール > MkDocs

More than 1 year has passed since last update.

ナイスで今風なドキュメントを自動生成してくれるMkDocs

MkDocs

image

前提

必須:python2.x or 3.x、pip
環境:pythonが動作する環境(Win、Mac、or ...)

※以下コマンドプロンプト(Win)or ターミナル(Mac)で進めます。

インストール

以下に添って進みます。

MkDocs - installation

python環境で進みます。Windowsの場合にはPythonプロンプトから実行してください。
pythonが入っていない方は上記の説明欄か別のpythonインストール記事を御覧ください。

### mkdocsインストール

pip install mkdocs

インストールが終わったら以下のコマンドで確認します。

mkdocs --version

バージョンが表示されればOKです。

mkdocs 事始め

試しに1作成します。
ドキュメントを配置するSite毎に1つのプロジェクトを作成します。
インストールガイドに倣ってmy-projectを作成します。
フォルダを作成したいカレントフォルダに移動して以下のコマンドを打ちます。

mkdocs new my-project

これでmy-projectフォルダが作成され、その下にmkdocs.ymlファイルとdocsフォルダが作成されます。

image

これからmkdocs.ymlに記載された設定に基づきドキュメントを作成していきますので、カレントフォルダをmy-projectに移動します。

cd my-project

サイトの確認

以下コマンドを打つことで現状(初期状態)をブラウザで確認できます。

mkdocs serve

以下のように結果が表示されればOK

INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes

アクセスしてみましょう

http://127.0.0.1:8000/ にアクセスしてみましょう。

image

自動再読み込み

mkdocs serveは自動再読み込みもサポートしており、設定ファイル、ドキュメントディレクトリ、またはテーマディレクトリ内の何かが変更されたときに自動で再構築されます。

試しにmkdocs.ymlを以下のように変更して保存します。

site_name: MkLorum

サイト名がMkLorumに変わります。

image

ページの追加

docsフォルダの下に新しいmdファイルをおいてもよいですが、
インストールガイドに従ってabout.mdファイルをcurl経由で追加します。
curlが未インストールの場合にはWindows > curlを使うにもインストール記事を書いてます。

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

Winの場合は以下
curl https://jaspervdj.be/lorem-markdownum/markdown.txt > docs/about.md

mkdocs.ymlを再保存すると自動でビルドが走りブラウザが更新されます。
image

doc下にファイルを追加するだけでもヘッダに反映されるようですが、
以下のようにファイルの順番を変更することもできます。

site_name: MkLorum
pages:
    - About: about.md
    - Home: index.md

image

テーマの変更

mkdocs.ymlに以下の設定を追加する事で簡単にテーマを変更できます。

theme: readthedocs

image

Favicon Iconの変更

割愛。公式ページを参照ください。

ビルド

内容に満足できたら(しなくてもいいですが)、ビルドしてHTMLファイルを作成します。

mkdocs build

これで、siteフォルダが作成されます。フォルダ配下は以下のような構成になっています。

image

siteフォルダをサーバー等に配置して公開しましょう。

ファイル構成が変わったり、ファイルの追加・削除を頻繁にした場合にはゴミファイルが残る場合があるのでそのような場合にはクリーンビルドします。

mkdocs build --clean

今回は以上です。

sugasaki
個人的なメモが多いです。 書いてる事は個人の見解であり所属する組織の公式見解ではありません
https://sugasaki.com/
runners
スポーツで世界を良くしたいエンジニアチーム。応援navi、.finisher、run&といった製品開発をしています!
https://www.wantedly.com/projects/167082
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした