Documentation

docs/philosophy.md

@@ -1,11 +1,46 @@
 ---
 template: overrides/main.html
-title: Getting started
 ---
 
-# Conventions
+# Philosophy
 
-## Symbols
+Before settling for Material for MkDocs, it's a good idea to understand the
+philosophy behind the project, in order to make sure it aligns with your goals.
+This page explains the design principles anchored in Material for MkDocs, and
+discusses the [conventions] used in this documentation.
+
+  [conventions]: #conventions
+
+## Design principles
+
+- __It's just Markdown__: Focus on the content of your documentation and create
+  a professional static site in minutes. No need to know HTML,CSS or JavaScript
+  – let Material for MkDocs do the heavy lifting for you.
+
+- __Works on all devices__: Serve your documentation with confidence – the 
+  underling layout automatically adapts to perfectly fit the available screen 
+  estate, no matter the type or size of the viewing device.
+
+- __Made to measure__: Change the colors, fonts, language, icons, logo and much
+  more with a few lines of configuration. Material for MkDocs can be easily 
+  extended and provides tons of options to alter appearance and behavior.
+
+- __Fast and lightweight__: Don't let your users wait – get incredible value
+  with a small footprint, by using one of the fastest themes around with
+  excellent performance, yielding great search engine rankings and happy
+  users that return.
+
+- __Accessible__: Make accessibility a priority – users can navigate your
+  documentation with touch devices, keyboard, and screen readers. Semantic
+  markup ensures that your documentation works for everyone.
+
+- __Open Source__: Trust 10,000+ users – choose a mature and well-funded
+  solution built with state-of-the-art Open Source technologies. Keep ownership
+  of your content without fear of vendor lock-in. Licensed under MIT.
+
+## Conventions
+
+### Symbols
 
 This documentation use some symbols for illustration purposes. Before you read
 on, please make sure you've made yourself familiar with the following list of
@@ -21,7 +56,7 @@ conventions:
 
 :   The tag icon in conjunction with a version number denotes when a specific 
     feature or behavior was added. Make sure you're at least on this version
-    before opening an issue.
+    if you want to use it.
 
 :octicons-file-code-24:   __{file.ext}__
 

mkdocs.yml

@@ -92,6 +92,7 @@ plugins:
   - redirects:
       redirect_maps:
         changelog/insiders.md: insiders/changelog.md
+        conventions.md: philosophy.md
         reference/meta-tags.md: reference/index.md
         reference/variables.md: https://mkdocs-macros-plugin.readthedocs.io/
         sponsorship.md: insiders/index.md
@@ -166,8 +167,8 @@ nav:
     - Publishing your site: publishing-your-site.md
     - Customization: customization.md
     - Browser support: browser-support.md
+    - Philosophy: philosophy.md
     - Alternatives: alternatives.md
-    - Conventions: conventions.md
     - License: license.md
     - Changelog:
       - changelog/index.md