From a4cc5409a657b6c23fa6bdc9e8a0cf6b48a309a1 Mon Sep 17 00:00:00 2001 From: Siming Yuan Date: Mon, 28 Feb 2022 11:45:05 -0500 Subject: [PATCH] adding support for mkdocs-material hosting/docs generation --- .gitignore | 1 + CONTRIBUTING.md | 22 ++++++++++++++++++++++ mkdocs.yml | 24 ++++++++++++++++++++++++ requirements.txt | 2 ++ 4 files changed, 49 insertions(+) create mode 100644 mkdocs.yml create mode 100644 requirements.txt diff --git a/.gitignore b/.gitignore index 9379563..e52d469 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ node_modules/ .history .DS_Store +site/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29882d4..44f81bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,3 +95,25 @@ - 确保分类正确，不和已有的菜名重复 - 确保签入的内容都符合 CC0 协议。尤其注意图片是否有水印！ - 确保他没有签入任何个人身份信息、EUII、Email 地址、GitHub 用户名 + + +## Documentation Hosting + +利用`mkdocs-material`来render markdown文件。 + +`./docs` 文件夹的存在是workaround mkdocs要求`.md`文件不能存在于根目录中。里面全部是relative symlink到 +实际的文件/文件夹 + +需求: Python > 3.6 + +如何使用： +``` +pip install -r requirements.txt +mkdocs serve +``` + +Documentation可以在本地 http://localhost:8000/ 打开。 + +管理员： +用`mkdocs build` 生成静态HTML网页, 存在于在`site/`文件夹下。Hosting的时候指向到`site/index.html`即可。 + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..45418b0 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,24 @@ +site_name: How To Cook +use_directory_urls: true +docs_dir: . +theme: + name: material + language: zh + features: + - navigation.instant + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: grey + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-night + name: Switch to light mode + +plugins: + - same-dir + - search diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..b23be6d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mkdocs-material +mkdocs-same-dir