MkDocs で何故か docs_dir の直下にある readme.md が変換されない件

MkDocs 1.0.4 の話。docs_dir で示したディレクトリに index.md と readme.md を置いていると、なぜか readme.md だけビルドの対象にならない。

原因は MkDocs のソースを見てようやくわかった。

index.md が存在する場合、readme.md のパースは無視される 仕様になっている。

該当ソース部分

from: https://github.com/mkdocs/mkdocs/blob/592e0852fe9e9c6c1316da818a8db402f73ff0c0/mkdocs/structure/files.py#L237

        for filename in _sort_files(filenames):
            path = os.path.normpath(os.path.join(relative_dir, filename))
            # Skip any excluded files
            if _filter_paths(basename=filename, path=path, is_dir=False, exclude=exclude):
                continue
            # Skip README.md is an index file also exists in dir
            if filename.lower() == 'readme.md' and 'index.md' in filenames:
                continue
            files.append(File(path, config['docs_dir'], config['site_dir'], config['use_directory_urls']))

1.0.4 後のバージョンでは log.warning が出そう

しかし現在進行のバージョンでは、log.warning による Warning メッセージが出るよう修正されている。

from: https://github.com/mkdocs/mkdocs/blob/cc03fd05876ad7ff14dfeff55832dc0dd7f0bf06/mkdocs/structure/files.py#L238

            if filename.lower() == 'readme.md' and 'index.md' in filenames:
                log.warning("Both index.md and readme.md found. Skipping readme.md from {}".format(source_dir))
continue