From e31e63fe864049adfaf14ee37409d77481ca80e4 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 15 Nov 2020 20:44:51 +0100 Subject: [PATCH] Fixed minimal configuration when installing from git --- docs/creating-your-site.md | 118 ++++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 47 deletions(-) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 42d7369bf..749ca88f4 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -41,22 +41,49 @@ This will create the following structure: ### Minimal configuration -Depending on your [installation method][2], you can now add the following lines -to `mkdocs.yml` in your project root. If you installed Material for MkDocs using -`pip` or `docker`, add: +To enable the theme, you can now simply add the following lines to `mkdocs.yml`. +Note that since there are several [installation methods][2], configuration will +be slightly different: -``` yaml -theme: - name: material -``` +=== "pip, docker" -If you cloned Material for MkDocs from GitHub, add: + ``` yaml + theme: + name: material + ``` -``` yaml -theme: - name: null - custom_dir: mkdocs-material/material -``` +=== "git" + + ``` yaml + theme: + name: null + custom_dir: mkdocs-material/material + + # 404 page + static_templates: + - 404.html + + # Necessary for search to work properly + include_search_page: false + search_index_only: true + + # Default values, taken from mkdocs_theme.yml + language: en + font: + text: Roboto + code: Roboto Mono + favicon: assets/favicon.png + icon: + logo: logo + ``` + +_If you cloned Material for MkDocs from GitHub, you must add all of the themes' +defaults by yourself, since_ [`mkdocs_theme.yml`][3] _is not loaded (as +[described in the official documentation][4])._ + + [2]: getting-started.md#installation + [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml + [4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme ### Advanced configuration @@ -64,34 +91,31 @@ Material for MkDocs comes with a lot of configuration options. The _setup_ section explains in great detail how to configure and customize colors, fonts, icons and much more: -* [Changing the colors][3] -* [Changing the fonts][4] -* [Changing the language][5] -* [Changing the logo and icons][6] -* [Setting up navigation][7] -* [Setting up site search][8] -* [Setting up site analytics][9] -* [Setting up versioning][10] -* [Setting up the header][11] -* [Setting up the footer][12] -* [Adding a git repository][13] -* [Adding a comment system][14] - +* [Changing the colors][5] +* [Changing the fonts][6] +* [Changing the language][7] +* [Changing the logo and icons][8] +* [Setting up navigation][9] +* [Setting up site search][10] +* [Setting up site analytics][11] +* [Setting up versioning][12] +* [Setting up the header][13] +* [Setting up the footer][14] +* [Adding a git repository][15] +* [Adding a comment system][16] - [2]: getting-started.md#installation - [3]: setup/changing-the-colors.md - [4]: setup/changing-the-fonts.md - [5]: setup/changing-the-language.md - [6]: setup/changing-the-logo-and-icons.md - [7]: setup/setting-up-navigation.md - [8]: setup/setting-up-site-search.md - [9]: setup/setting-up-site-analytics.md - [10]: setup/setting-up-versioning.md - [11]: setup/setting-up-the-header.md - [12]: setup/setting-up-the-footer.md - [13]: setup/adding-a-git-repository.md - [14]: setup/adding-a-comment-system.md - + [5]: setup/changing-the-colors.md + [6]: setup/changing-the-fonts.md + [7]: setup/changing-the-language.md + [8]: setup/changing-the-logo-and-icons.md + [9]: setup/setting-up-navigation.md + [10]: setup/setting-up-site-search.md + [11]: setup/setting-up-site-analytics.md + [12]: setup/setting-up-versioning.md + [13]: setup/setting-up-the-header.md + [14]: setup/setting-up-the-footer.md + [15]: setup/adding-a-git-repository.md + [16]: setup/adding-a-comment-system.md ## Previewing as you write @@ -117,12 +141,12 @@ If you're running Material for MkDocs from within Docker, use: docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material ``` -Point your browser to [localhost:8000][15] and you should see: +Point your browser to [localhost:8000][17] and you should see: -[![Creating your site][16]][15] +[![Creating your site][18]][18] - [15]: http://localhost:8000 - [16]: assets/screenshots/creating-your-site.png + [17]: http://localhost:8000 + [18]: assets/screenshots/creating-your-site.png ## Building your site @@ -135,8 +159,8 @@ mkdocs build The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. -The site can be hosted on [GitHub Pages][17], [GitLab Pages][18], a CDN of your +The site can be hosted on [GitHub Pages][19], [GitLab Pages][20], a CDN of your choice or your private web space. - [17]: publishing-your-site.md#github-pages - [18]: publishing-your-site.md#gitlab-pages + [19]: publishing-your-site.md#github-pages + [20]: publishing-your-site.md#gitlab-pages