⬆️ Upgrade to MkDocs Material 5 and update docs scripts (#1225)

* ⬆️ Upgrade mkdocs.yml configs for MkDocs Material 5

* ✨ Update docs.py to always update mkdocs.yml

* 🌐 Update mkdocs.yml for translations

* 🔧 Update MkDocs config

* ✨ Add tabs for alternative options

* ⬆️ Update termynal setup with new CSS classes

* 🔧 Sync / Update mkdocs.yml for languages

docs/en/docs/advanced/settings.md

@@ -15,35 +15,37 @@ An <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-
 
 You can create and use environment variables in the shell, without needing Python:
 
-<div class="termy">
+=== "Linux, macOS, Windows Bash"
 
-```console
+    <div class="termy">
-// You could create an env var MY_NAME with
-$ export MY_NAME="Wade Wilson"
 
-// Then you could use it with other programs, like
+    ```console
-$ echo "Hello $MY_NAME"
+    // You could create an env var MY_NAME with
+    $ export MY_NAME="Wade Wilson"
 
-Hello Wade Wilson
+    // Then you could use it with other programs, like
-```
+    $ echo "Hello $MY_NAME"
 
-</div>
+    Hello Wade Wilson
+    ```
 
-Or in PowerShell in Windows:
+    </div>
 
-<div class="termy">
+=== "Windows PowerShell"
 
-```console
+    <div class="termy">
-// Create an env var MY_NAME
-$ $Env:MY_NAME = "Wade Wilson"
 
-// Use it with other programs, like
+    ```console
-$ echo "Hello $Env:MY_NAME"
+    // Create an env var MY_NAME
+    $ $Env:MY_NAME = "Wade Wilson"
 
-Hello Wade Wilson
+    // Use it with other programs, like
-```
+    $ echo "Hello $Env:MY_NAME"
 
-</div>
+    Hello Wade Wilson
+    ```
+
+    </div>
 
 ### Read env vars in Python
 

docs/en/docs/contributing.md

@@ -24,59 +24,67 @@ That will create a directory `./env/` with the Python binaries and then you will
 
 Activate the new environment with:
 
-<div class="termy">
+=== "Linux, macOS"
 
-```console
+    <div class="termy">
-$ source ./env/bin/activate
-```
 
-</div>
+    ```console
+    $ source ./env/bin/activate
+    ```
 
-Or in Windows' PowerShell:
+    </div>
 
-<div class="termy">
+=== "Windows PowerShell"
 
-```console
+    <div class="termy">
-$ .\env\Scripts\Activate.ps1
-```
 
-</div>
+    ```console
+    $ .\env\Scripts\Activate.ps1
+    ```
 
-Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
+    </div>
 
-<div class="termy">
+=== "Windows Bash"
 
-```console
+    Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
-$ source ./env/Scripts/activate
-```
 
-</div>
+    <div class="termy">
+
+    ```console
+    $ source ./env/Scripts/activate
+    ```
+
+    </div>
 
 To check it worked, use:
 
-<div class="termy">
+=== "Linux, macOS, Windows Bash"
 
-```console
+    <div class="termy">
-$ which pip
 
-some/directory/fastapi/env/bin/pip
+    ```console
-```
+    $ which pip
 
-</div>
+    some/directory/fastapi/env/bin/pip
+    ```
 
-If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+    </div>
 
-Or in Windows PowerShell:
+=== "Windows PowerShell"
 
-<div class="termy">
+    <div class="termy">
 
-```console
+    ```console
-$ Get-Command pip
+    $ Get-Command pip
+
+    some/directory/fastapi/env/bin/pip
+    ```
+
+    </div>
+
+If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
 
-some/directory/fastapi/env/bin/pip
-```
 
-</div>
 
 !!! tip
     Every time you install a new package with `pip` under that environment, activate the environment again.
@@ -103,27 +111,31 @@ Now re-activate the environment to make sure you are using the `flit` you just i
 
 And now use `flit` to install the development dependencies:
 
-<div class="termy">
+=== "Linux, macOS"
 
-```console
+    <div class="termy">
-$ flit install --deps develop --symlink
 
----> 100%
+    ```console
-```
+    $ flit install --deps develop --symlink
 
-</div>
+    ---> 100%
+    ```
 
-If you are on Windows, use `--pth-file` instead of `--symlink`:
+    </div>
 
-<div class="termy">
+=== "Windows"
 
-```console
+    If you are on Windows, use `--pth-file` instead of `--symlink`:
-$ flit install --deps develop --pth-file
 
----> 100%
+    <div class="termy">
-```
 
-</div>
+    ```console
+    $ flit install --deps develop --pth-file
+
+    ---> 100%
+    ```
+
+    </div>
 
 It will install all the dependencies and your local FastAPI in your local environment.
 

docs/en/docs/deployment.md

@@ -329,55 +329,61 @@ You can deploy **FastAPI** directly without Docker too.
 
 You just need to install an ASGI compatible server like:
 
-* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
+=== "Uvicorn"
 
-<div class="termy">
+    * <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
 
-```console
+    <div class="termy">
-$ pip install uvicorn
 
----> 100%
+    ```console
-```
+    $ pip install uvicorn
 
-</div>
+    ---> 100%
+    ```
 
-* <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
+    </div>
 
-<div class="termy">
+=== "Hypercorn"
 
-```console
+    * <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
-$ pip install hypercorn
 
----> 100%
+    <div class="termy">
-```
 
-</div>
+    ```console
+    $ pip install hypercorn
+
+    ---> 100%
+    ```
 
-...or any other ASGI server.
+    </div>
+
+    ...or any other ASGI server.
 
 And run your application the same way you have done in the tutorials, but without the `--reload` option, e.g.:
 
-<div class="termy">
+=== "Uvicorn"
 
-```console
+    <div class="termy">
-$ uvicorn main:app --host 0.0.0.0 --port 80
 
-<span style="color: green;">INFO</span>:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
+    ```console
-```
+    $ uvicorn main:app --host 0.0.0.0 --port 80
 
-</div>
+    <span style="color: green;">INFO</span>:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
+    ```
 
-or with Hypercorn:
+    </div>
 
-<div class="termy">
+=== "Hypercorn"
 
-```console
+    <div class="termy">
-$ hypercorn main:app --bind 0.0.0.0:80
 
-Running on 0.0.0.0:8080 over http (CTRL + C to quit)
+    ```console
-```
+    $ hypercorn main:app --bind 0.0.0.0:80
 
-</div>
+    Running on 0.0.0.0:8080 over http (CTRL + C to quit)
+    ```
+
+    </div>
 
 You might want to set up some tooling to make sure it is restarted automatically if it stops.
 

docs/en/docs/js/custom.js

@@ -35,7 +35,7 @@ function setupTermynal() {
 
     function createTermynals() {
         document
-            .querySelectorAll(`.${termynalActivateClass} .codehilite`)
+            .querySelectorAll(`.${termynalActivateClass} .highlight`)
             .forEach(node => {
                 const text = node.textContent;
                 const lines = text.split("\n");

docs/en/mkdocs.yml

@@ -6,6 +6,8 @@ theme:
   palette:
     primary: teal
     accent: amber
+  icon:
+    repo: fontawesome/brands/github-alt
   logo: img/icon-white.svg
   favicon: img/favicon.png
   language: en
@@ -129,19 +131,20 @@ markdown_extensions:
     - name: mermaid
       class: mermaid
       format: !!python/name:pymdownx.superfences.fence_div_format ''
+- pymdownx.tabbed
 extra:
   social:
-  - type: github
+  - icon: fontawesome/brands/github-alt
     link: https://github.com/tiangolo/typer
-  - type: twitter
+  - icon: fontawesome/brands/twitter
     link: https://twitter.com/tiangolo
-  - type: linkedin
+  - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/in/tiangolo
-  - type: rss
+  - icon: fontawesome/brands/dev
     link: https://dev.to/tiangolo
-  - type: medium
+  - icon: fontawesome/brands/medium
     link: https://medium.com/@tiangolo
-  - type: globe
+  - icon: fontawesome/solid/globe
     link: https://tiangolo.com
 extra_css:
 - css/termynal.css

docs/es/mkdocs.yml

@@ -6,6 +6,8 @@ theme:
   palette:
     primary: teal
     accent: amber
+  icon:
+    repo: fontawesome/brands/github-alt
   logo: https://fastapi.tiangolo.com/img/icon-white.svg
   favicon: https://fastapi.tiangolo.com/img/favicon.png
   language: es
@@ -37,19 +39,20 @@ markdown_extensions:
     - name: mermaid
       class: mermaid
       format: !!python/name:pymdownx.superfences.fence_div_format ''
+- pymdownx.tabbed
 extra:
   social:
-  - type: github
+  - icon: fontawesome/brands/github-alt
     link: https://github.com/tiangolo/typer
-  - type: twitter
+  - icon: fontawesome/brands/twitter
     link: https://twitter.com/tiangolo
-  - type: linkedin
+  - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/in/tiangolo
-  - type: rss
+  - icon: fontawesome/brands/dev
     link: https://dev.to/tiangolo
-  - type: medium
+  - icon: fontawesome/brands/medium
     link: https://medium.com/@tiangolo
-  - type: globe
+  - icon: fontawesome/solid/globe
     link: https://tiangolo.com
 extra_css:
 - https://fastapi.tiangolo.com/css/termynal.css
@@ -58,3 +61,5 @@ extra_javascript:
 - https://unpkg.com/[email protected]/dist/mermaid.min.js
 - https://fastapi.tiangolo.com/js/termynal.js
 - https://fastapi.tiangolo.com/js/custom.js
+- https://fastapi.tiangolo.com/js/chat.js
+- https://sidecar.gitter.im/dist/sidecar.v1.js

docs/pt/mkdocs.yml

@@ -6,6 +6,8 @@ theme:
   palette:
     primary: teal
     accent: amber
+  icon:
+    repo: fontawesome/brands/github-alt
   logo: https://fastapi.tiangolo.com/img/icon-white.svg
   favicon: https://fastapi.tiangolo.com/img/favicon.png
   language: pt
@@ -37,19 +39,20 @@ markdown_extensions:
     - name: mermaid
       class: mermaid
       format: !!python/name:pymdownx.superfences.fence_div_format ''
+- pymdownx.tabbed
 extra:
   social:
-  - type: github
+  - icon: fontawesome/brands/github-alt
     link: https://github.com/tiangolo/typer
-  - type: twitter
+  - icon: fontawesome/brands/twitter
     link: https://twitter.com/tiangolo
-  - type: linkedin
+  - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/in/tiangolo
-  - type: rss
+  - icon: fontawesome/brands/dev
     link: https://dev.to/tiangolo
-  - type: medium
+  - icon: fontawesome/brands/medium
     link: https://medium.com/@tiangolo
-  - type: globe
+  - icon: fontawesome/solid/globe
     link: https://tiangolo.com
 extra_css:
 - https://fastapi.tiangolo.com/css/termynal.css

docs/zh/mkdocs.yml

@@ -6,6 +6,8 @@ theme:
   palette:
     primary: teal
     accent: amber
+  icon:
+    repo: fontawesome/brands/github-alt
   logo: https://fastapi.tiangolo.com/img/icon-white.svg
   favicon: https://fastapi.tiangolo.com/img/favicon.png
   language: zh
@@ -37,19 +39,20 @@ markdown_extensions:
     - name: mermaid
       class: mermaid
       format: !!python/name:pymdownx.superfences.fence_div_format ''
+- pymdownx.tabbed
 extra:
   social:
-  - type: github
+  - icon: fontawesome/brands/github-alt
     link: https://github.com/tiangolo/typer
-  - type: twitter
+  - icon: fontawesome/brands/twitter
     link: https://twitter.com/tiangolo
-  - type: linkedin
+  - icon: fontawesome/brands/linkedin
     link: https://www.linkedin.com/in/tiangolo
-  - type: rss
+  - icon: fontawesome/brands/dev
     link: https://dev.to/tiangolo
-  - type: medium
+  - icon: fontawesome/brands/medium
     link: https://medium.com/@tiangolo
-  - type: globe
+  - icon: fontawesome/solid/globe
     link: https://tiangolo.com
 extra_css:
 - https://fastapi.tiangolo.com/css/termynal.css

scripts/docs.py

@@ -20,6 +20,12 @@ missing_translation_snippet = """
 """
 
 docs_path = Path("docs")
+en_docs_path = Path("docs/en")
+en_config_path: Path = en_docs_path / mkdocs_name
+
+
+def get_en_config() -> dict:
+    return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
 
 
 def get_lang_paths():
@@ -43,39 +49,15 @@ def complete_existing_lang(incomplete: str):
             yield lang_path.name
 
 
-@app.command()
+def get_base_lang_config(lang: str):
-def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
+    en_config = get_en_config()
-    """
-    Generate a new docs translation directory for the language LANG.
-
-    LANG should be a 2-letter language code, like: en, es, de, pt, etc.
-    """
-    new_path: Path = Path("docs") / lang
-    if new_path.exists():
-        typer.echo(f"The language was already created: {lang}")
-        raise typer.Abort()
-    new_path.mkdir()
-    en_docs_path = Path("docs/en")
-    en_config_path: Path = en_docs_path / mkdocs_name
-    en_config: dict = mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
     fastapi_url_base = "https://fastapi.tiangolo.com/"
-    new_config = {}
+    new_config = en_config.copy()
-    new_config["site_name"] = en_config["site_name"]
-    new_config["site_description"] = en_config["site_description"]
     new_config["site_url"] = en_config["site_url"] + f"{lang}/"
-    new_config["theme"] = en_config["theme"]
     new_config["theme"]["logo"] = fastapi_url_base + en_config["theme"]["logo"]
     new_config["theme"]["favicon"] = fastapi_url_base + en_config["theme"]["favicon"]
     new_config["theme"]["language"] = lang
-    new_config["repo_name"] = en_config["repo_name"]
-    new_config["repo_url"] = en_config["repo_url"]
-    new_config["edit_uri"] = en_config["edit_uri"]
-    new_config["google_analytics"] = en_config["google_analytics"]
     new_config["nav"] = en_config["nav"][:2]
-
-    new_config["markdown_extensions"] = en_config["markdown_extensions"]
-    new_config["extra"] = en_config["extra"]
-
     extra_css = []
     css: str
     for css in en_config["extra_css"]:
@@ -93,6 +75,22 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
         else:
             extra_js.append(fastapi_url_base + js)
     new_config["extra_javascript"] = extra_js
+    return new_config
+
+
+@app.command()
+def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
+    """
+    Generate a new docs translation directory for the language LANG.
+
+    LANG should be a 2-letter language code, like: en, es, de, pt, etc.
+    """
+    new_path: Path = Path("docs") / lang
+    if new_path.exists():
+        typer.echo(f"The language was already created: {lang}")
+        raise typer.Abort()
+    new_path.mkdir()
+    new_config = get_base_lang_config(lang)
     new_config_path: Path = Path(new_path) / mkdocs_name
     new_config_path.write_text(
         yaml.dump(new_config, sort_keys=False, width=200), encoding="utf-8"
@@ -280,7 +278,15 @@ def live(
 def update_config(lang: str):
     lang_path: Path = docs_path / lang
     config_path = lang_path / mkdocs_name
-    config: dict = mkdocs.utils.yaml_load(config_path.read_text(encoding="utf-8"))
+    current_config: dict = mkdocs.utils.yaml_load(
+        config_path.read_text(encoding="utf-8")
+    )
+    if lang == "en":
+        config = get_en_config()
+    else:
+        config = get_base_lang_config(lang)
+        config["nav"] = current_config["nav"]
+        config["theme"]["language"] = current_config["theme"]["language"]
     languages = [{"en": "/"}]
     for lang in get_lang_paths():
         if lang.name == "en" or not lang.is_dir():