diff --git a/docs/setup/index.md b/docs/setup/index.md new file mode 100644 index 000000000..994321608 --- /dev/null +++ b/docs/setup/index.md @@ -0,0 +1,117 @@ +# Setup + +Material for MkDocs offers a wide range of options for customizing and adjusting +your documentation. In this section, we will explain how to make the most use of +Material for MkDocs to change the look of your documentation, add more content, +improve its functionality, and work with extensions. + +## Customizing the look + +Make your documentation reflect your brand by changing its colors, fonts, icons, +logo, and more with just a few lines of configuration. Material for MkDocs makes +it easy to extend the basic configurations and provides many options to alter +the appearance. + +
+ +- :material-brush-variant: __[Colors]__ – Change colors with an existing color palette or customize with CSS +- :fontawesome-regular-file-word: __[Fonts]__ – Change fonts using Google Fonts or load self-hosted fonts +- :material-google-downasaur: __[Logo & Icons]__ – Change the logo, use any of the +8,000 icons, or add new ones + +
+ + [Colors]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/ + [Fonts]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/ + [Logo & Icons]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/ + +## Adding additional content + +Easily extend the content of your documentation. Adjusting headers, including a +footer, creating a blog, implementing comment systems, and automatically creating +social media previews. + +
+ +- :material-format-header-1: __[Header]__ – Customize the header using different configurations +- :material-format-font-size-decrease: __[Footer]__ – Add links to social media or other websites in the footer +- :material-cards-variant: __[Social Cards]__ – Create automated Social Media previews when sharing links +- :material-book-open-outline: __[Blog]__ – Build a standalone blog or expand your documentation with one +- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer + +
+ + [Header]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-header/ + [Footer]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/ + [Social Cards]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/ + [Blog]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/ + [Comment System]: https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/ + +## Enhancing functionality + +Improve the functionality of your documentation by integrating navigation and +site search, categorizing pages using tags, changing the language, or adding +multiple languages, and deploying multiple versions. + +
+ +- :material-navigation-variant-outline: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure +- :material-tab-search: __[Site Search]__ – Set up an excellent client-side search implementation +- :fontawesome-solid-earth-americas: __[Language]__ – Change the language using one of the +50 existing translations +- :octicons-tag-16: __[Tags]__ – Categorize your pages with tags and group related pages +- :octicons-versions-16: __[Versioning]__ – Deploy multiple versions by integrating with external utilities + +
+ + [Navigation]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/ + [Site Search]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/ + [Language]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/ + [Tags]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/ + [Versioning]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/ + +## Optimizing your site + +Optimize your site by displaying information from your Git repository, getting a +higher ranking on search engines, ensuring compliance with data privacy +regulations, and unlocking offline usage. + +
+ +- :fontawesome-brands-git: __[Git Repository]__ – Display information to your project's repository on your static site +- :material-screwdriver: __[Optimized site]__ – Create optimized sites that rank great on search engines, i.a. +- :octicons-lock-16: __[Data Privacy]__ – Ensure compliance with data privacy regulations +- :octicons-cloud-offline-16: __[Offline usage]__ – Build an online and offline-capable documentation + +
+ + [Git Repository]: https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/ + [Optimized site]: https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/ + [Data Privacy]: https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/ + [Offline usage]: https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/ + +## Working with extensions + +Extend the range of available features and enhance your technical writing by +working with extensions in your documentation. + +
+ +- :material-language-python: __[Python Markdown]__ – Unlock a large range of features that require Python Markdown +- :material-plus-box: __[Python Markdown Extension]__ – Advance your technical writing with a collection of extensions + +
+ + [Python Markdown]: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/ + [Python Markdown Extension]: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/ + +## Dependencies + +Install external libraries to allow for image processing as part of the build +pipeline to make use of social cards and image optimization features. + +
+ +- :fontawesome-regular-image: __[Image processing]__ – Install external libraries for image processing during the build pipeline + +
+ + [Image processing]: https://squidfunk.github.io/mkdocs-material/setup/dependencies/image-processing/ diff --git a/mkdocs.yml b/mkdocs.yml index c120475fb..25f00ac59 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -179,6 +179,7 @@ nav: - Guides: - Creating a reproduction: guides/creating-a-reproduction.md - Setup: + - setup/index.md - Changing the colors: setup/changing-the-colors.md - Changing the fonts: setup/changing-the-fonts.md - Changing the language: setup/changing-the-language.md