Mkdocs、このオープンソースソフトウェアのおかげでドキュメントを作成する

次の記事では、Mkdocsを見ていきます。 ソフトウェアを開発して求める場合 ドキュメントを作成するためのプラットフォーム あなたのプロジェクトのXNUMXつ。 または、スタッフの内部ドキュメントを作成する必要がある会社で働いている場合。 あなたがいくつかのメモを保存したい上級ユーザーであっても。 MkDocsはあなたが試してみるべきツールです。

このソフトウェアは、ドキュメントプラットフォームの作成を目的とした静的サイトジェネレーターです。 非常にシンプルで、見た目も美しく、セットアップと展開も簡単です。 です Pythonで書かれた そして単に マークダウン形式でファイルを作成する必要があります。 次に、単一のYAML構成ファイルを使用して、適切な静的Webサイトを生成できます。

次に、MkDocsを使用して完全なドキュメントWebサイトを取得するのがいかに簡単であるかを見ていきます。 他にもたくさんあります サイトジェネレーター 同様の静的ですが、これ 最も単純な構成と実装があります.

通常のユーザーもこのソフトウェアを使用して メモを取るためのローカルプラットフォームを作成する 自分自身または他の同様のもののために。

MkDocsをインストールする

ローカルにインストールする

MkDocsのインストールはとても簡単だと見てみましょう。 できる pipを使用してインストールします。 ターミナルを開いて（Ctrl + Alt + T）、次のように書き込むだけです。

pip install mkdocs

インストール後、作業ディレクトリで次のコマンドを実行します。 サイトを初期化する:

mkdocs new mkdocspro

そして それを提供し始める 実行：

cd mkdocspro

mkdocs serve

その後、あなたはすることができます ローカルホストに移動：8000 (またはポート8000​​のIPアドレス/ホスト名）MkDocsがどのように機能するかを確認します。

nginxサーバーにインストールします

これは静的サイトジェネレータであるため、 PHPやPythonのようなバックエンドエンジンは必要ありません。 MkDocsプロジェクトをWebサーバー（nginx、apache2）にXNUMX分で実装できるようになります。 たとえば、ここに nginx仮想ホスト構成:

server {
        server_name ejemplo.com;

        root /var/www/mkdocspro/sitio;
        index index.html;

        location / {
                try_files $uri $uri/ =404;
        }
}

置き換えます ejemplo.com サーバー上にあるドメインを使用します。 また、変更する必要があります / var / www / mkdocspro / site サーバー上のサイトのサブフォルダーのパスによって。 それから私達は nginxを再起動します 次のコマンドを使用します。

sudo service nginx restart

これで、example.comにアクセスして、それが機能することを確認できます。

Mkdocsに別のテーマをインストールする

デフォルトのMkdocsテーマは特に良くありません。 ただし、XNUMX分で別のインストールを行うことができます。 別のテーマのインストール例は次のとおりです。 一緒に行く マテリアルテーマをインストールする:

pip install mkdocs-material

インストール後、テーマをアクティブ化するには、次のことを行う必要があります mkdocs.ymlファイルを編集して、これと同じようにします。 いくつかのオプションを追加できます。

site_name: Proyecto MkDocs
site_url: 'http://ejemplo.com'
repo_url: 'https://github.com/nombreusuario/proyectourlongithub'
edit_uri: edit/master
site_description: 'Aquí una descripción corta.'
google_analytics: ['UA-xxxxxxxxx-x', 'ejemplo.com']
extra:
  favicon: 'https://ejemplo/favicon.png'
  social:
    - type: 'github'
      link: 'https://github.com/xxxxxx'
    - type: 'facebook'
      link: 'https://facebook.com/xxxxxxx'
    - type: 'twitter'
      link: 'https://twitter.com/xxxxxxx'
  disqus: 'minombredisqus'
  theme: 'material'

オプションは非常に明確です。 しかし、ここにいくつかの説明があります：

• リポ_url： それは GitリポジトリのURL。 GitをMkDocsプロジェクトに直接統合することを計画している場合は、このオプションを使用して、ユーザーがページを編集したり、プロジェクトをフォークしたりできるようにすることができます。
• edit_uri： これは GitHubのページを編集するための接尾辞。 GitLabまたはGitBucketを使用している場合は、変更できます。
• グーグルアナリティクス：MkDocsのコントロールパネルはありません。 したがって、知るために あなたのウェブサイトにアクセスする人は、GoogleAnalyticsを使用する必要があります。 このオプションを使用すると、追跡番号を挿入して、アカウントをWebサイトに関連付けることができます。
• 分遅れ： お望みならば Disqusコメントシステムを有効にする ウェブサイトで、ここにあなたの短い名前を挿入することができます。
• テーマ： 使用したいテーマの名前。 マテリアルテーマで行ったように、事前にインストールする必要があります。 これは、例で使用する名前になります。

新しいテーマの変更を見る

ファイルを保存した後、 mkdocsprojectフォルダー内でmkdocsビルドを実行します。 Webサイトは、マテリアルテーマのデフォルトのルックアンドフィールを採用します。

重要： 変更するたびに、必ずmkdocsビルドを実行してください あなたがファイルで行うこと。 それ以外の場合、変更は表示されません。

多くがあります 他のテーマとオプション このソフトウェアを構成します。 あなたはでそれらを参照することができます 公式ドキュメント MkDocsによる。 これがのリストです 可能なオプション 使用できます。