Mkdocs，借助此開源軟件創建文檔

在下一篇文章中，我們將看一下Mkdocs。 如果您開發軟件並尋求 創建文檔的平台 為您的項目之一。 或者，如果您在一家需要為員工創建內部文檔的公司中工作。 即使您是想保存一些筆記的高級用戶。 MkDocs是您應該嘗試的工具。

該軟件是一個靜態站點生成器，旨在創建文檔平台。 它非常簡單，外觀漂亮，並且易於設置和部署。 這個 用python編寫 和簡單地 要求您以Markdown格式創建文件。 然後，使用單個YAML配置文件，您可以生成一個適合您的靜態網站。

接下來，我們將看到使用MkDocs獲得完整的文檔網站是多麼容易。 還有很多 網站生成器 類似的靜態，但這 具有最簡單的配置和實現.

普通用戶也可以使用此軟件來 創建一個本地平台來做筆記 為自己或其他類似的東西。

安裝MkDocs

本地安裝

讓我們看一下，安裝MkDocs非常簡單。 我們可以 使用pip安裝它。 您只需要打開一個終端（Ctrl + Alt + T）並輸入以下內容即可：

pip install mkdocs

安裝後，在您的工作目錄中，運行以下命令以： 初始化網站:

mkdocs new mkdocspro

然後 開始服務 跑：

cd mkdocspro

mkdocs serve

然後你可以 轉到本地主機：8000 (或您的IP地址/主機名（帶有端口8000）），以了解MkDocs的工作原理。

在您的Nginx服務器上安裝

由於這是靜態網站生成器， 不需要像PHP或Python這樣的後端引擎。 您將能夠在一分鐘內在Web服務器（nginx，apache2）上實現MkDocs項目。 例如，這是 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主題不是特別好。 但是您可以在一分鐘內安裝另一個。 下面是安裝另一個主題的一個示例。 我們將要與之一起 安裝材料主題:

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'

選項很明確。 但是這裡有一些解釋：

• 回購網址： 是個 Git存儲庫URL。 如果您打算將Git直接集成到您的MkDocs項目中，則可以使用此選項允許人們編輯頁面或創建項目。
• 編輯_uri：這是 用於在GitHub上編輯頁面的後綴。 如果您使用的是GitLab或GitBucket，則可以更改它。
• google_analytics：沒有MkDocs的控制面板。 因此，要知道 誰訪問了您的網站，您必須使用Google Analytics（分析）。 該選項將允許您插入跟踪號，以將您的帳戶與網站相關聯。
• disqus： 如果你想 啟用Disqus評論系統 在網站上，您可以在此處輸入您的簡稱。
• 主題：The 您要使用的主題名稱。 您將必須事先安裝它，就像我們對材質主題所做的那樣。 這將是我們在示例中使用的名稱。

查看新主題的變化

保存文件後， 在mkdocsproject文件夾中運行mkdocs build。 您的網站將採用Material主題的默認外觀：

重要事項： 確保每次修改後始終運行mkdocs build 您在文件中執行的操作。 否則，您將看不到任何變化。

有很多 其他主題和選項 配置此軟件。 您可以在 官方文件 由MkDocs。 這是一個清單 可能的選擇 我們可以使用的。