Mkdocs用拡張機能_プラグイン等のメモ¶

これまでの、個人用 Mkdocs の、
pip install してきた、拡張機能_プラグイン等、のメモです。

■mkdocs¶

mkdocs のインストール
pip install mkdocs

■mkdocs-material¶

おすすめであるマテリアルデザインのテーマをダウンロード
pip install mkdocs-material

■pygments¶

プログラムのコードをハイライトをかけることができるライブラリをダウンロード
pip install pygments

■mkdocs-git-revision-date-localized-plugin¶

mkdocs-のgit-改訂日付局在-プラグイン
は、マークダウンファイルが最後に各ページの一番下に更新された日付が追加されるようになる。
pip install mkdocs-git-revision-date-localized-plugin

■mkdocs-awesome-pages-plugin¶

Folder以下に .pages というymlで書かれた定義を読み込んで、
Folder名や、Folder以下のページの並び順を制御できるようになる。
pip install mkdocs-awesome-pages-plugin

実行例

PS C:\Users\███\work\mkdocs> pip install mkdocs-awesome-pages-plugin
Collecting mkdocs-awesome-pages-plugin
  Downloading mkdocs_awesome_pages_plugin-2.2.1-py3-none-any.whl (7.9 kB)
Requirement already satisfied: mkdocs>=1 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs-awesome-pages-plugin) (1.0.4)
Requirement already satisfied: livereload>=2.5.1 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (2.6.1)
Requirement already satisfied: tornado>=5.0 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (6.0.3)
Requirement already satisfied: click>=3.3 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (7.0)
Requirement already satisfied: Jinja2>=2.7.1 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (2.11.1)
Requirement already satisfied: Markdown>=2.3.1 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (3.2.1)
Requirement already satisfied: PyYAML>=3.10 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from mkdocs>=1->mkdocs-awesome-pages-plugin) (5.3)
Requirement already satisfied: six in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from livereload>=2.5.1->mkdocs>=1->mkdocs-awesome-pages-plugin) (1.14.0)
Requirement already satisfied: MarkupSafe>=0.23 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from Jinja2>=2.7.1->mkdocs>=1->mkdocs-awesome-pages-plugin) (1.1.1)
Requirement already satisfied: setuptools>=36 in c:\users\███\program\python-3.7.6-amd64\lib\site-packages (from Markdown>=2.3.1->mkdocs>=1->mkdocs-awesome-pages-plugin) (41.2.0)
Installing collected packages: mkdocs-awesome-pages-plugin
Successfully installed mkdocs-awesome-pages-plugin-2.2.1

オリジナルの mkdocs-awesome-pages-plugin ドキュメント
https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin

更に、以下を実施する。

詳細

mkdocs.yml　への追記
tech_memo/docsと同階層にある、mkdocs.yml への追記を施す。
追記内容:
1 2
plugins: - awesome-pages
能率化用の python ファイルの作成と実行
手動で .pages ファイルを作成するわずらわしさの解消、能率の良い素早いページ作成を可能としたいため、
あんどう氏は、1つの素晴らしい python ファイルを作成し、能率化を図っているそうですので、
私も活用する事にします。
いつもお世話になっている、あんどう氏のサイト
awesome-pagesというプラグイン
を参考にさせていただきました。いつもありがとうございます。
続いて、
tech_memo/docsと同階層に、create_mkdocs_pages.py を作成し、常駐させておきます。
~~[あんどう氏の create_mkdocs_pages.py(古い格納箇所)]~~(~~https://github.com/fereria/reincarnation_tech/blob/master/create_mkdocs_pages.py~~){target=_blank}
あんどう氏の create_mkdocs_pages.py(新規格納箇所)
を参考に、個人用にアレンジ作成させて頂きました。

create_mkdocs_pages.py（個人用）

#!python3.6
# -*- coding: utf-8 -*-
u"""
    mkdocs用のDir用ファイル自動生成

    note:
        筆者は、
        フォルダ名の prefix に、基本的に ソート index を目的として、2ケタの数字を付加するようにしています。
        e.g.):"00_ちょと古い記事 でも参考", "05_Maya"   etc...
    note:
        当ツールは、html作成時に、prefix数字を隠してソート表示する目的で、 .pages を作成します。
        html 作成時には、 .pages ファイルの記述内容が優先され、認識の上で、 html をソート表示します。
        但し、同階層直下には何らかの、 index.md ファイル　が存在しなければ、表示すらもされません。
    note:
        基本、 当、python ファイル を誤って実行し、
        意図していないフォルダ直下に、 .pages が作成されてしまったとしても、
        その該当フォルダと同階層直下にある index.md ファイルのヘッダーに、
        ---
        title: フォルダ名
        ---
        の記述がない限り、html に悪影響はおよぼしません！！！！
"""

import os
import os.path
import re
import codecs
import glob
import sys

# 基本、英語表記フォルダ名である方がベターだが、
# 日本語のIndexにしたいものは、key(フォルダ名)から、value　↓への名前に置換した,
# title: FOLDER_REPLACE_STRING[key]が、
# .pages ファイルのヘッダーに記述される.
# e.g.): FOLDER_REPLACE_STRING["basic_operation"] は "基本操作"
FOLDER_REPLACE_STRING = {
    # "basic_operation": "基本操作"
    # , "data_structure": "データ構造"
    # , u"ご意見等はｺﾁﾗから": "mail"
}

# 無視するフォルダ
# note): 階層下の全フォルダを探してしまいます！！
EXCLUSION = ["css", "custom_dir", "images", "img", "unused", "node_modules", "templates",
             "javascripts"
             ]

# --------------------------------------------------------- #


def replace_title_folder_name(name):

    buff = re.sub("[0-9][0-9]_", "", name)
    for key in FOLDER_REPLACE_STRING.keys():
        buff = buff.replace(key, FOLDER_REPLACE_STRING[key])
    return buff


def create_pages(root_path):

    def recursive_file_check(path):

        if os.path.isdir(path):
            # Folderのとき
            if root_path != path:
                dirname = path.split("/")[-1]
                if dirname not in EXCLUSION:
                    title = replace_title_folder_name(dirname)
                    print(f"create .pages {path}/{dirname}")
                    with codecs.open(path + "/.pages", 'w', 'utf-8') as f:
                        f.write(f"title: {title}")
            files = os.listdir(path)
            for file in files:
                recursive_file_check(path + "/" + file)

    recursive_file_check(root_path)


if __name__ == "__main__":
    create_pages(os.getcwd() + "/docs")

あとは、
Terminal or PowerShell で、
tech_memoフォルダと同階層まで、カレントを移動しておいて、
cd C:\Users\███\work\mkdocs\tech_memo

以下を実行
python create_mkdocs_pages.py
すると、実行の都度、新規上書きで、 .pages ファイルが各々のファルダ内に出来る。

以上

最終更新日: 2024年6月21日 14:58:10

Mkdocs用 拡張機能_プラグイン等 のメモ¶