Formatting

material/.overrides/hooks/translations.py

@@ -38,8 +38,8 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files):
         return
 
     # Collect all existing languages
-    names: dict[str, str] = dict()
+    names: dict[str, str] = {}
-    known: dict[str, dict[str, str]] = dict()
+    known: dict[str, dict[str, str]] = {}
     for path in glob("src/partials/languages/*.html"):
         with open(path, "r", encoding = "utf-8") as f:
             data = f.read()

material/plugins/blog/plugin.py

@@ -237,7 +237,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
         # is not already present, so we can remove footnotes or other content
         # from the excerpt without affecting the content of the excerpt
         if separator not in page.markdown:
-            path = page.file.src_uri
+            path = page.file.src_path
             if self.config.post_excerpt == "required":
                 raise PluginError(
                     f"Couldn't find '{separator}' separator in '{path}'"
@@ -415,7 +415,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
         docs = os.path.relpath(config.docs_dir)
         file = os.path.join(docs, path)
         if not os.path.isfile(file):
-            authors: dict[str, Author] = dict()
+            authors: dict[str, Author] = {}
             return authors
 
         # Open file and parse as YAML

material/plugins/blog/structure/__init__.py

@@ -109,8 +109,8 @@ class Post(Page):
 
         # Excerpts are subsets of posts that are used in pages like archive and
         # category views. They are not rendered as standalone pages, but are
-        # included in the context of the parent post. Each post has a dedicated
+        # rendered in the context of a view. Each post has a dedicated excerpt
-        # excerpt instance which is reused when rendering views.
+        # instance which is reused when rendering views.
         self.excerpt: Excerpt = None
 
         # Initialize authors and actegories

material/plugins/info/plugin.py

@@ -87,8 +87,7 @@ class InfoPlugin(BasePlugin[InfoConfig]):
         # hack to detect whether the custom_dir setting was used without parsing
         # mkdocs.yml again - we check at which position the directory provided
         # by the theme resides, and if it's not the first one, abort.
-        path = get_theme_dir(config.theme.name)
+        if config.theme.dirs.index(get_theme_dir(config.theme.name)):
-        if config.theme.dirs.index(path):
             log.error("Please remove 'custom_dir' setting.")
             self._help_on_customizations_and_exit()
 
@@ -130,7 +129,7 @@ class InfoPlugin(BasePlugin[InfoConfig]):
                 ]))
             )
 
-            # Add information in platform
+            # Add information on platform
             f.writestr(
                 os.path.join(example, "platform.json"),
                 json.dumps(

material/plugins/search/plugin.py

@@ -299,7 +299,7 @@ class Element:
     """
 
     # Initialize HTML element
-    def __init__(self, tag, attrs = dict()):
+    def __init__(self, tag, attrs = {}):
         self.tag   = tag
         self.attrs = attrs
 

material/plugins/social/plugin.py

@@ -18,6 +18,19 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+# -----------------------------------------------------------------------------
+# Disclaimer
+# -----------------------------------------------------------------------------
+# Please note: this version of the social plugin is not actively development
+# anymore. Instead, Material for MkDocs Insiders ships a complete rewrite of
+# the plugin which is much more powerful and addresses all shortcomings of
+# this implementation. Additionally, the new social plugin allows to create
+# entirely custom social cards. You can probably imagine, that this was a lot
+# of work to pull off. If you run into problems, or want to have additional
+# functionality, please consider sponsoring the project. You can then use the
+# new version of the plugin immediately.
+# -----------------------------------------------------------------------------
+
 import concurrent.futures
 import functools
 import logging
@@ -159,7 +172,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
             )
             sys.exit(1)
 
-        # Generate social card if not in cache - TODO: values from mkdocs.yml
+        # Generate social card if not in cache
         hash = md5("".join([
             site_name,
             str(title),
@@ -267,17 +280,6 @@ class SocialPlugin(BasePlugin[SocialConfig]):
                 lines.append(words)
                 words = [word]
 
-        # # Balance words on last line - TODO: overflows when broken word is too long
-        # if len(lines) > 0:
-        #     prev = len(" ".join(lines[-1]))
-        #     last = len(" ".join(words))#
-
-        #     print(last, prev)
-
-        #     # Heuristic: try to find a good ratio
-        #     if last / prev < 0.6:
-        #         words.insert(0, lines[-1].pop())
-
         # Join words for each line and create image
         lines.append(words)
         lines = [" ".join(line) for line in lines]
@@ -424,7 +426,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
         font_filename_base = name.replace(' ', '')
         filename_regex = re.escape(font_filename_base)+r"-(\w+)\.[ot]tf$"
 
-        font = dict()
+        font = {}
         # Check for cached files - note these may be in subfolders
         for currentpath, folders, files in os.walk(self.cache):
             for file in files:

material/plugins/tags/config.py

@@ -35,7 +35,7 @@ class TagsConfig(Config):
 
     # Options for tags
     tags_file = Optional(Type(str))
-    tags_extra_files = Type(dict, default = dict())
+    tags_extra_files = Type(dict, default = {})
     tags_slugify = Type((type(slugify), partial), default = slugify)
     tags_slugify_separator = Type(str, default = "-")
     tags_compare = Optional(Type(type(casefold)))

src/.overrides/hooks/translations.py

@@ -38,8 +38,8 @@ def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files):
         return
 
     # Collect all existing languages
-    names: dict[str, str] = dict()
+    names: dict[str, str] = {}
-    known: dict[str, dict[str, str]] = dict()
+    known: dict[str, dict[str, str]] = {}
     for path in glob("src/partials/languages/*.html"):
         with open(path, "r", encoding = "utf-8") as f:
             data = f.read()

src/plugins/blog/plugin.py

@@ -237,7 +237,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
         # is not already present, so we can remove footnotes or other content
         # from the excerpt without affecting the content of the excerpt
         if separator not in page.markdown:
-            path = page.file.src_uri
+            path = page.file.src_path
             if self.config.post_excerpt == "required":
                 raise PluginError(
                     f"Couldn't find '{separator}' separator in '{path}'"
@@ -415,7 +415,7 @@ class BlogPlugin(BasePlugin[BlogConfig]):
         docs = os.path.relpath(config.docs_dir)
         file = os.path.join(docs, path)
         if not os.path.isfile(file):
-            authors: dict[str, Author] = dict()
+            authors: dict[str, Author] = {}
             return authors
 
         # Open file and parse as YAML

src/plugins/blog/structure/__init__.py

@@ -109,8 +109,8 @@ class Post(Page):
 
         # Excerpts are subsets of posts that are used in pages like archive and
         # category views. They are not rendered as standalone pages, but are
-        # included in the context of the parent post. Each post has a dedicated
+        # rendered in the context of a view. Each post has a dedicated excerpt
-        # excerpt instance which is reused when rendering views.
+        # instance which is reused when rendering views.
         self.excerpt: Excerpt = None
 
         # Initialize authors and actegories

src/plugins/info/plugin.py

@@ -87,8 +87,7 @@ class InfoPlugin(BasePlugin[InfoConfig]):
         # hack to detect whether the custom_dir setting was used without parsing
         # mkdocs.yml again - we check at which position the directory provided
         # by the theme resides, and if it's not the first one, abort.
-        path = get_theme_dir(config.theme.name)
+        if config.theme.dirs.index(get_theme_dir(config.theme.name)):
-        if config.theme.dirs.index(path):
             log.error("Please remove 'custom_dir' setting.")
             self._help_on_customizations_and_exit()
 
@@ -130,7 +129,7 @@ class InfoPlugin(BasePlugin[InfoConfig]):
                 ]))
             )
 
-            # Add information in platform
+            # Add information on platform
             f.writestr(
                 os.path.join(example, "platform.json"),
                 json.dumps(

src/plugins/search/plugin.py

@@ -299,7 +299,7 @@ class Element:
     """
 
     # Initialize HTML element
-    def __init__(self, tag, attrs = dict()):
+    def __init__(self, tag, attrs = {}):
         self.tag   = tag
         self.attrs = attrs
 

src/plugins/social/plugin.py

@@ -18,6 +18,19 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+# -----------------------------------------------------------------------------
+# Disclaimer
+# -----------------------------------------------------------------------------
+# Please note: this version of the social plugin is not actively development
+# anymore. Instead, Material for MkDocs Insiders ships a complete rewrite of
+# the plugin which is much more powerful and addresses all shortcomings of
+# this implementation. Additionally, the new social plugin allows to create
+# entirely custom social cards. You can probably imagine, that this was a lot
+# of work to pull off. If you run into problems, or want to have additional
+# functionality, please consider sponsoring the project. You can then use the
+# new version of the plugin immediately.
+# -----------------------------------------------------------------------------
+
 import concurrent.futures
 import functools
 import logging
@@ -159,7 +172,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
             )
             sys.exit(1)
 
-        # Generate social card if not in cache - TODO: values from mkdocs.yml
+        # Generate social card if not in cache
         hash = md5("".join([
             site_name,
             str(title),
@@ -267,17 +280,6 @@ class SocialPlugin(BasePlugin[SocialConfig]):
                 lines.append(words)
                 words = [word]
 
-        # # Balance words on last line - TODO: overflows when broken word is too long
-        # if len(lines) > 0:
-        #     prev = len(" ".join(lines[-1]))
-        #     last = len(" ".join(words))#
-
-        #     print(last, prev)
-
-        #     # Heuristic: try to find a good ratio
-        #     if last / prev < 0.6:
-        #         words.insert(0, lines[-1].pop())
-
         # Join words for each line and create image
         lines.append(words)
         lines = [" ".join(line) for line in lines]
@@ -424,7 +426,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
         font_filename_base = name.replace(' ', '')
         filename_regex = re.escape(font_filename_base)+r"-(\w+)\.[ot]tf$"
 
-        font = dict()
+        font = {}
         # Check for cached files - note these may be in subfolders
         for currentpath, folders, files in os.walk(self.cache):
             for file in files:

src/plugins/tags/config.py

@@ -35,7 +35,7 @@ class TagsConfig(Config):
 
     # Options for tags
     tags_file = Optional(Type(str))
-    tags_extra_files = Type(dict, default = dict())
+    tags_extra_files = Type(dict, default = {})
     tags_slugify = Type((type(slugify), partial), default = slugify)
     tags_slugify_separator = Type(str, default = "-")
     tags_compare = Optional(Type(type(casefold)))