From 3832f67d50702706e1755fde9741759ed7821a7b Mon Sep 17 00:00:00 2001
From: Lucain <lucainp@gmail.com>
Date: Wed, 21 Jun 2023 14:06:35 +0200
Subject: [PATCH] Migrate doc files to Markdown (#1522)

* Migrate doc files to Markdown

* remove inference_client.mdx
---
 docs/source/concepts/{git_vs_http.mdx => git_vs_http.md}   | 4 ++++
 docs/source/guides/{community.mdx => community.md}         | 4 ++++
 docs/source/guides/{download.mdx => download.md}           | 4 ++++
 .../guides/{hf_file_system.mdx => hf_file_system.md}       | 4 ++++
 docs/source/guides/{inference.mdx => inference.md}         | 4 ++++
 docs/source/guides/{integrations.mdx => integrations.md}   | 4 ++++
 docs/source/guides/{manage-cache.mdx => manage-cache.md}   | 4 ++++
 docs/source/guides/{manage-spaces.mdx => manage-spaces.md} | 4 ++++
 docs/source/guides/{model-cards.mdx => model-cards.md}     | 4 ++++
 docs/source/guides/{overview.mdx => overview.md}           | 4 ++++
 docs/source/guides/{repository.mdx => repository.md}       | 4 ++++
 docs/source/guides/{search.mdx => search.md}               | 4 ++++
 docs/source/guides/{upload.mdx => upload.md}               | 4 ++++
 .../guides/{webhooks_server.mdx => webhooks_server.md}     | 4 ++++
 docs/source/{index.mdx => index.md}                        | 4 ++++
 docs/source/{installation.mdx => installation.md}          | 4 ++++
 docs/source/package_reference/{cache.mdx => cache.md}      | 4 ++++
 docs/source/package_reference/{cards.mdx => cards.md}      | 4 ++++
 .../package_reference/{community.mdx => community.md}      | 4 ++++
 ...{environment_variables.mdx => environment_variables.md} | 4 ++++
 .../{file_download.mdx => file_download.md}                | 4 ++++
 docs/source/package_reference/{hf_api.mdx => hf_api.md}    | 4 ++++
 .../{hf_file_system.mdx => hf_file_system.md}              | 4 ++++
 .../{inference_client.mdx => inference_client.md}          | 4 ++++
 docs/source/package_reference/{login.mdx => login.md}      | 4 ++++
 docs/source/package_reference/{mixins.mdx => mixins.md}    | 4 ++++
 docs/source/package_reference/overview.md                  | 7 +++++++
 docs/source/package_reference/overview.mdx                 | 3 ---
 .../package_reference/{repository.mdx => repository.md}    | 4 ++++
 .../{space_runtime.mdx => space_runtime.md}                | 4 ++++
 .../package_reference/{tensorboard.mdx => tensorboard.md}  | 4 ++++
 .../package_reference/{utilities.mdx => utilities.md}      | 4 ++++
 .../{webhooks_server.mdx => webhooks_server.md}            | 4 ++++
 docs/source/{quick-start.mdx => quick-start.md}            | 4 ++++
 34 files changed, 135 insertions(+), 3 deletions(-)
 rename docs/source/concepts/{git_vs_http.mdx => git_vs_http.md} (95%)
 rename docs/source/guides/{community.mdx => community.md} (96%)
 rename docs/source/guides/{download.mdx => download.md} (98%)
 rename docs/source/guides/{hf_file_system.mdx => hf_file_system.md} (96%)
 rename docs/source/guides/{inference.mdx => inference.md} (98%)
 rename docs/source/guides/{integrations.mdx => integrations.md} (98%)
 rename docs/source/guides/{manage-cache.mdx => manage-cache.md} (99%)
 rename docs/source/guides/{manage-spaces.mdx => manage-spaces.md} (98%)
 rename docs/source/guides/{model-cards.mdx => model-cards.md} (98%)
 rename docs/source/guides/{overview.mdx => overview.md} (96%)
 rename docs/source/guides/{repository.mdx => repository.md} (98%)
 rename docs/source/guides/{search.mdx => search.md} (97%)
 rename docs/source/guides/{upload.mdx => upload.md} (99%)
 rename docs/source/guides/{webhooks_server.mdx => webhooks_server.md} (98%)
 rename docs/source/{index.mdx => index.md} (95%)
 rename docs/source/{installation.mdx => installation.md} (97%)
 rename docs/source/package_reference/{cache.mdx => cache.md} (86%)
 rename docs/source/package_reference/{cards.mdx => cards.md} (90%)
 rename docs/source/package_reference/{community.mdx => community.md} (79%)
 rename docs/source/package_reference/{environment_variables.mdx => environment_variables.md} (97%)
 rename docs/source/package_reference/{file_download.mdx => file_download.md} (81%)
 rename docs/source/package_reference/{hf_api.mdx => hf_api.md} (93%)
 rename docs/source/package_reference/{hf_file_system.mdx => hf_file_system.md} (77%)
 rename docs/source/package_reference/{inference_client.mdx => inference_client.md} (92%)
 rename docs/source/package_reference/{login.mdx => login.md} (61%)
 rename docs/source/package_reference/{mixins.mdx => mixins.md} (80%)
 create mode 100644 docs/source/package_reference/overview.md
 delete mode 100644 docs/source/package_reference/overview.mdx
 rename docs/source/package_reference/{repository.mdx => repository.md} (87%)
 rename docs/source/package_reference/{space_runtime.mdx => space_runtime.md} (76%)
 rename docs/source/package_reference/{tensorboard.mdx => tensorboard.md} (84%)
 rename docs/source/package_reference/{utilities.mdx => utilities.md} (97%)
 rename docs/source/package_reference/{webhooks_server.mdx => webhooks_server.md} (93%)
 rename docs/source/{quick-start.mdx => quick-start.md} (96%)

diff --git a/docs/source/concepts/git_vs_http.mdx b/docs/source/concepts/git_vs_http.md
similarity index 95%
rename from docs/source/concepts/git_vs_http.mdx
rename to docs/source/concepts/git_vs_http.md
index 4cdb7270c0..05cff6e6db 100644
--- a/docs/source/concepts/git_vs_http.mdx
+++ b/docs/source/concepts/git_vs_http.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Git vs HTTP paradigm
 
 The `huggingface_hub` library is a library for interacting with the Hugging Face Hub, which is a 
diff --git a/docs/source/guides/community.mdx b/docs/source/guides/community.md
similarity index 96%
rename from docs/source/guides/community.mdx
rename to docs/source/guides/community.md
index 3119cb059e..ba6979fe80 100644
--- a/docs/source/guides/community.mdx
+++ b/docs/source/guides/community.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Interact with Discussions and Pull Requests 
 
 The `huggingface_hub` library provides a Python interface to interact with Pull Requests and Discussions on the Hub.
diff --git a/docs/source/guides/download.mdx b/docs/source/guides/download.md
similarity index 98%
rename from docs/source/guides/download.mdx
rename to docs/source/guides/download.md
index cfca4a2e79..d538e04049 100644
--- a/docs/source/guides/download.mdx
+++ b/docs/source/guides/download.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Download files from the Hub
 
 The `huggingface_hub` library provides functions to download files from the repositories
diff --git a/docs/source/guides/hf_file_system.mdx b/docs/source/guides/hf_file_system.md
similarity index 96%
rename from docs/source/guides/hf_file_system.mdx
rename to docs/source/guides/hf_file_system.md
index 7d0d5581a3..5c68232168 100644
--- a/docs/source/guides/hf_file_system.mdx
+++ b/docs/source/guides/hf_file_system.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Interact with the Hub through the Filesystem API
 
 In addition to the [`HfApi`], the `huggingface_hub` library provides [`HfFileSystem`], a pythonic [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) file interface to the Hugging Face Hub. The [`HfFileSystem`] builds of top of the [`HfApi`] and offers typical filesystem style operations like `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, and `put_file`.
diff --git a/docs/source/guides/inference.mdx b/docs/source/guides/inference.md
similarity index 98%
rename from docs/source/guides/inference.mdx
rename to docs/source/guides/inference.md
index 5cb59e30dd..a6ea1c0800 100644
--- a/docs/source/guides/inference.mdx
+++ b/docs/source/guides/inference.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Run Inference on servers
 
 Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive,
diff --git a/docs/source/guides/integrations.mdx b/docs/source/guides/integrations.md
similarity index 98%
rename from docs/source/guides/integrations.mdx
rename to docs/source/guides/integrations.md
index dc3fd26d8c..87575a4e8a 100644
--- a/docs/source/guides/integrations.mdx
+++ b/docs/source/guides/integrations.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Integrate any ML framework with the Hub
 
 The Hugging Face Hub makes hosting and sharing models with the community easy. It supports
diff --git a/docs/source/guides/manage-cache.mdx b/docs/source/guides/manage-cache.md
similarity index 99%
rename from docs/source/guides/manage-cache.mdx
rename to docs/source/guides/manage-cache.md
index f3b9861535..9b9b1dd718 100644
--- a/docs/source/guides/manage-cache.mdx
+++ b/docs/source/guides/manage-cache.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Manage `huggingface_hub` cache-system
 
 ## Understand caching
diff --git a/docs/source/guides/manage-spaces.mdx b/docs/source/guides/manage-spaces.md
similarity index 98%
rename from docs/source/guides/manage-spaces.mdx
rename to docs/source/guides/manage-spaces.md
index fe5f1e0299..e7f0892803 100644
--- a/docs/source/guides/manage-spaces.mdx
+++ b/docs/source/guides/manage-spaces.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Manage your Space
 
 In this guide, we will see how to manage your Space runtime
diff --git a/docs/source/guides/model-cards.mdx b/docs/source/guides/model-cards.md
similarity index 98%
rename from docs/source/guides/model-cards.mdx
rename to docs/source/guides/model-cards.md
index ff21610e94..c8eb7dc52e 100644
--- a/docs/source/guides/model-cards.mdx
+++ b/docs/source/guides/model-cards.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Create and share Model Cards
 
 The `huggingface_hub` library provides a Python interface to create, share, and update Model Cards.
diff --git a/docs/source/guides/overview.mdx b/docs/source/guides/overview.md
similarity index 96%
rename from docs/source/guides/overview.mdx
rename to docs/source/guides/overview.md
index ff611c1b26..5dd0a035d5 100644
--- a/docs/source/guides/overview.mdx
+++ b/docs/source/guides/overview.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # How-to guides
 
 In this section, you will find practical guides to help you achieve a specific goal.
diff --git a/docs/source/guides/repository.mdx b/docs/source/guides/repository.md
similarity index 98%
rename from docs/source/guides/repository.mdx
rename to docs/source/guides/repository.md
index 643520ec6b..f0987a52ab 100644
--- a/docs/source/guides/repository.mdx
+++ b/docs/source/guides/repository.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Create and manage a repository
 
 The Hugging Face Hub is a collection of git repositories. [Git](https://git-scm.com/) is a widely used tool in software
diff --git a/docs/source/guides/search.mdx b/docs/source/guides/search.md
similarity index 97%
rename from docs/source/guides/search.mdx
rename to docs/source/guides/search.md
index 417d8d552a..8d4076631b 100644
--- a/docs/source/guides/search.mdx
+++ b/docs/source/guides/search.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Search the Hub
 
 In this tutorial, you will learn how to search models, datasets and spaces on the Hub using `huggingface_hub`.
diff --git a/docs/source/guides/upload.mdx b/docs/source/guides/upload.md
similarity index 99%
rename from docs/source/guides/upload.mdx
rename to docs/source/guides/upload.md
index a20c85d71b..112238a09a 100644
--- a/docs/source/guides/upload.mdx
+++ b/docs/source/guides/upload.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Upload files to the Hub
 
 Sharing your files and work is an important aspect of the Hub. The `huggingface_hub` offers several options for uploading your files to the Hub. You can use these functions independently or integrate them into your library, making it more convenient for your users to interact with the Hub. This guide will show you how to push files:
diff --git a/docs/source/guides/webhooks_server.mdx b/docs/source/guides/webhooks_server.md
similarity index 98%
rename from docs/source/guides/webhooks_server.mdx
rename to docs/source/guides/webhooks_server.md
index 55219281eb..1545c22938 100644
--- a/docs/source/guides/webhooks_server.mdx
+++ b/docs/source/guides/webhooks_server.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Webhooks Server
 
 Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to
diff --git a/docs/source/index.mdx b/docs/source/index.md
similarity index 95%
rename from docs/source/index.mdx
rename to docs/source/index.md
index 1e1b20937a..15efbb1dd5 100644
--- a/docs/source/index.mdx
+++ b/docs/source/index.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # 🤗 Hub client library
 
 The `huggingface_hub` library allows you to interact with the [Hugging Face
diff --git a/docs/source/installation.mdx b/docs/source/installation.md
similarity index 97%
rename from docs/source/installation.mdx
rename to docs/source/installation.md
index 4ddd412691..423051e10c 100644
--- a/docs/source/installation.mdx
+++ b/docs/source/installation.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Installation
 
 Before you start, you will need to setup your environment by installing the appropriate packages.
diff --git a/docs/source/package_reference/cache.mdx b/docs/source/package_reference/cache.md
similarity index 86%
rename from docs/source/package_reference/cache.mdx
rename to docs/source/package_reference/cache.md
index aefbb55b39..b3326c239e 100644
--- a/docs/source/package_reference/cache.mdx
+++ b/docs/source/package_reference/cache.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Cache-system reference
 
 The caching system was updated in v0.8.0 to become the central cache-system shared
diff --git a/docs/source/package_reference/cards.mdx b/docs/source/package_reference/cards.md
similarity index 90%
rename from docs/source/package_reference/cards.mdx
rename to docs/source/package_reference/cards.md
index d10f8146d2..4f64238bd7 100644
--- a/docs/source/package_reference/cards.mdx
+++ b/docs/source/package_reference/cards.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Repository Cards
 
 The huggingface_hub library provides a Python interface to create, share, and update Model/Dataset Cards. 
diff --git a/docs/source/package_reference/community.mdx b/docs/source/package_reference/community.md
similarity index 79%
rename from docs/source/package_reference/community.mdx
rename to docs/source/package_reference/community.md
index 6ddfe470d3..d41d45c8a6 100644
--- a/docs/source/package_reference/community.mdx
+++ b/docs/source/package_reference/community.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Interacting with Discussions and Pull Requests
 
 Check the [`HfApi`] documentation page for the reference of methods enabling
diff --git a/docs/source/package_reference/environment_variables.mdx b/docs/source/package_reference/environment_variables.md
similarity index 97%
rename from docs/source/package_reference/environment_variables.mdx
rename to docs/source/package_reference/environment_variables.md
index 4a99b2743d..32eeb553d7 100644
--- a/docs/source/package_reference/environment_variables.mdx
+++ b/docs/source/package_reference/environment_variables.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Environment variables
 
 `huggingface_hub` can be configured using environment variables.
diff --git a/docs/source/package_reference/file_download.mdx b/docs/source/package_reference/file_download.md
similarity index 81%
rename from docs/source/package_reference/file_download.mdx
rename to docs/source/package_reference/file_download.md
index bd8551f429..bb4066c79d 100644
--- a/docs/source/package_reference/file_download.mdx
+++ b/docs/source/package_reference/file_download.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Downloading files
 
 ## Download a single file
diff --git a/docs/source/package_reference/hf_api.mdx b/docs/source/package_reference/hf_api.md
similarity index 93%
rename from docs/source/package_reference/hf_api.mdx
rename to docs/source/package_reference/hf_api.md
index 3f1f4c1034..8dd7e19828 100644
--- a/docs/source/package_reference/hf_api.mdx
+++ b/docs/source/package_reference/hf_api.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # HfApi Client
 
 Below is the documentation for the `HfApi` class, which serves as a Python wrapper for the Hugging Face Hub's API.
diff --git a/docs/source/package_reference/hf_file_system.mdx b/docs/source/package_reference/hf_file_system.md
similarity index 77%
rename from docs/source/package_reference/hf_file_system.mdx
rename to docs/source/package_reference/hf_file_system.md
index 5911d971a2..af2db68792 100644
--- a/docs/source/package_reference/hf_file_system.mdx
+++ b/docs/source/package_reference/hf_file_system.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Filesystem API
 
 The `HfFileSystem` class provides a pythonic file interface to the Hugging Face Hub based on [`fssepc`](https://filesystem-spec.readthedocs.io/en/latest/).
diff --git a/docs/source/package_reference/inference_client.mdx b/docs/source/package_reference/inference_client.md
similarity index 92%
rename from docs/source/package_reference/inference_client.mdx
rename to docs/source/package_reference/inference_client.md
index 1c16aff053..ded8be8d84 100644
--- a/docs/source/package_reference/inference_client.mdx
+++ b/docs/source/package_reference/inference_client.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Inference
 
 Inference is the process of using a trained model to make predictions on new data. As this process can be compute-intensive,
diff --git a/docs/source/package_reference/login.mdx b/docs/source/package_reference/login.md
similarity index 61%
rename from docs/source/package_reference/login.mdx
rename to docs/source/package_reference/login.md
index bf26c55697..c100e3999b 100644
--- a/docs/source/package_reference/login.mdx
+++ b/docs/source/package_reference/login.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Login and logout
 
 The `huggingface_hub` library allows users to programmatically login and logout the
diff --git a/docs/source/package_reference/mixins.mdx b/docs/source/package_reference/mixins.md
similarity index 80%
rename from docs/source/package_reference/mixins.mdx
rename to docs/source/package_reference/mixins.md
index 3c56d0c3b9..41480dfa80 100644
--- a/docs/source/package_reference/mixins.mdx
+++ b/docs/source/package_reference/mixins.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Mixins & serialization methods
 
 ## Mixins
diff --git a/docs/source/package_reference/overview.md b/docs/source/package_reference/overview.md
new file mode 100644
index 0000000000..f024f25692
--- /dev/null
+++ b/docs/source/package_reference/overview.md
@@ -0,0 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
+# Overview
+
+This section contains an exhaustive and technical description of `huggingface_hub` classes and methods.
\ No newline at end of file
diff --git a/docs/source/package_reference/overview.mdx b/docs/source/package_reference/overview.mdx
deleted file mode 100644
index d84781cd31..0000000000
--- a/docs/source/package_reference/overview.mdx
+++ /dev/null
@@ -1,3 +0,0 @@
-# Overview
-
-This section contains an exhaustive and technical description of `huggingface_hub` classes and methods.
\ No newline at end of file
diff --git a/docs/source/package_reference/repository.mdx b/docs/source/package_reference/repository.md
similarity index 87%
rename from docs/source/package_reference/repository.mdx
rename to docs/source/package_reference/repository.md
index 5c01c69323..9964f94859 100644
--- a/docs/source/package_reference/repository.mdx
+++ b/docs/source/package_reference/repository.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Managing local and online repositories
 
 The `Repository` class is a helper class that wraps `git` and `git-lfs` commands. It provides tooling adapted
diff --git a/docs/source/package_reference/space_runtime.mdx b/docs/source/package_reference/space_runtime.md
similarity index 76%
rename from docs/source/package_reference/space_runtime.mdx
rename to docs/source/package_reference/space_runtime.md
index 52308a5dfe..014207b6fe 100644
--- a/docs/source/package_reference/space_runtime.mdx
+++ b/docs/source/package_reference/space_runtime.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Managing your Space runtime
 
 Check the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub.
diff --git a/docs/source/package_reference/tensorboard.mdx b/docs/source/package_reference/tensorboard.md
similarity index 84%
rename from docs/source/package_reference/tensorboard.mdx
rename to docs/source/package_reference/tensorboard.md
index 76ad1a3d72..560f03a19f 100644
--- a/docs/source/package_reference/tensorboard.mdx
+++ b/docs/source/package_reference/tensorboard.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # TensorBoard logger
 
 TensorBoard is a visualization toolkit for machine learning experimentation. TensorBoard allows tracking and visualizing
diff --git a/docs/source/package_reference/utilities.mdx b/docs/source/package_reference/utilities.md
similarity index 97%
rename from docs/source/package_reference/utilities.mdx
rename to docs/source/package_reference/utilities.md
index 35c533c766..93e73e6c7e 100644
--- a/docs/source/package_reference/utilities.mdx
+++ b/docs/source/package_reference/utilities.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Utilities
 
 ## Configure logging
diff --git a/docs/source/package_reference/webhooks_server.mdx b/docs/source/package_reference/webhooks_server.md
similarity index 93%
rename from docs/source/package_reference/webhooks_server.mdx
rename to docs/source/package_reference/webhooks_server.md
index 9e747eff04..3d6847a3e0 100644
--- a/docs/source/package_reference/webhooks_server.mdx
+++ b/docs/source/package_reference/webhooks_server.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Webhooks Server
 
 Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to
diff --git a/docs/source/quick-start.mdx b/docs/source/quick-start.md
similarity index 96%
rename from docs/source/quick-start.mdx
rename to docs/source/quick-start.md
index 0740172e2c..8d6e52b889 100644
--- a/docs/source/quick-start.mdx
+++ b/docs/source/quick-start.md
@@ -1,3 +1,7 @@
+<!--⚠️ Note that this file is in Markdown but contain specific syntax for our doc-builder (similar to MDX) that may not be
+rendered properly in your Markdown viewer.
+-->
+
 # Quickstart
 
 The [Hugging Face Hub](https://huggingface.co/) is the go-to place for sharing machine learning