Add custom icons and update MkDocs configuration

Added multiple SVG branding logos to overrides/.icons and a README for icon usage. Updated mkdocs.yml to enhance theme customization, navigation, plugins, and markdown extensions, including support for custom icons, improved code block features, and additional plugins for privacy and media optimization.

Author: santaimpersonator

mkdocs.yml

@@ -14,10 +14,12 @@ copyright:
 # Default edit/view actions to "main" branch, instead of "master"
 edit_uri: blob/main/docs/
 
+
 # Configuration for webpage theme
 theme:
   # Theme: https://squidfunk.github.io/mkdocs-material/
   name: material
+  custom_dir: overrides # Personalized changes to the theme
 
   # Icon in Browser Tab (must be a square image - i.e. 32x32 pixels)
   favicon: assets/img/sfe-logo.png
@@ -27,39 +29,49 @@ theme:
     text: Roboto
     code: Roboto Mono
 
+
   # Features to Include (ref. theme documentation)
   features:
-
-    # Enable copy button on code blocks
+    # Enable the copy button on code blocks
     - content.code.copy
 
+    # Enables code selection button to link a specific section of a code block
+    - content.code.select
+
     # Enable annotations in code blocks
     - content.code.annotate
 
     # Enable "view source" and "edit this page" buttons
     - content.action.edit
     # - content.action.view
 
+    # Enable tooltips (pop-open dialog boxes)
+    - content.tooltips
+
     # Enable Navigation buttons in the footer (i.e. previous/next)
     - navigation.footer
 
-    # Enables anchor tracking (updates page url with the section user is on)
+    # Enables anchor tracking (updates page URL with the section the user is on)
     # i.e. https://docs.sparkfun.com/<page link>/#<sub-section>
     - navigation.tracking
     - navigation.tabs.sticky
 
     # Enables tabs for navigating the website
     - navigation.tabs
+
     # Keeps tabs visible in the header when scrolling
     - navigation.tabs.sticky
 
     # Adds pop-up button just below the header (when the user starts to scroll up)
-    # Allows users to easily jump to the beginning of the page
+    # i.e. Allows users to easily jump to the beginning of the page
     - navigation.top
 
-    # Renders path for page navigation at top of the page (makes page navigation more mobile friendly)
+    # Renders path for page navigation at the top of the page (makes page navigation more mobile friendly)
     - navigation.path
 
+    # Highlights all occurrences of a search result when clicked on
+    - search.highlight
+
 
   # Adds light/dark theme to the webpage
   palette:
@@ -89,6 +101,7 @@ theme:
         icon: material/weather-night
         name: Switch to light mode
 
+
   # Configures icons
   icon:
     # Sets homepage icon
@@ -118,6 +131,7 @@ theme:
       # Add custom admonitions
       github: simple/github
       arduino: simple/arduino
+      rpi: simple/raspberrypi
       python: simple/python
       code: fontawesome/regular/file-code
       terminal: octicons/terminal-16
@@ -126,83 +140,198 @@ theme:
       # Permalink icon
       link: octicons/link-16
 
-  # Adds overrides for stylesheets, html, etc.
-  custom_dir: overrides
-
 
 # Included MkDocs plugins
 # Add the installation of any new plugins to the ./github/workflows/mkdocs.yml file also
 plugins:
+  # Default search plugin
   - search
+
+  # Allows formatting (code block, icons, etc.) in headings and titles
   - typeset
+
+  # Redirects page navigation
   - redirects:
       redirect_maps:
-          'index.md': 'introduction.md'
+        'index.md': 'introduction.md'
+
+  # Enables improved security for external links
+  - privacy:
+      # Disables plugin on local builds
+      enabled: !ENV [CI, false]
+
+      # Disables cache mechanism, so that external assets can be updated during rebuilds
+      cache: false
+
+      # # Allows for external assets to be used
+      # assets: true
+      # assets_fetch: true
+
+      # Provide domains for assets that are retrieved from external sites
+      # assets_include:
+      #   - https://docs.sparkfun.com/
+
+      # assets_fetch_dir: /docs
+
+      # External links open in a new tab
+      links_attr_map:
+        target: _blank
+      links_noopener: true
+
+  # Optimizes media files (*.png and *.jpg)
+  - optimize:
+      # Disables plugin on local builds
+      enabled: !ENV [CI, false]
+
+      # Specify directory; otherwise, multiple instances are created (.cache/plugins and .cache/plugin)
+      cache_dir: .cache/plugins/optimize
+
+      # Default values (from auto-complete)
+      # ------------------------------
+      # enabled: true
+      # cache: true
+      # cache_dir: .cache/plugins/optimize
+      # optimize_png: true
+      # optimize_png_speed: 4
+      # optimize_png_strip: true
+      # optimize_jpg: true
+      # optimize_jpg_quality: 60
+      # optimize_jpg_progressive: true
+      # print_gain: true
+      # print_gain_summary: true
+
+
   # Add revision date
   - git-revision-date-localized:
+      # Disables plugin on local builds
+      enabled: !ENV [CI, false]
+
       enable_creation_date: true
       type: timeago
+
   # Add git committers at bottom of the page
   - git-committers:
+      # Disables plugin on local builds
+      enabled: !ENV [CI, false]
+
       repository: sparkfun/SparkFun_BlueSMiRF-v2
       branch: main
-  # Add git authors at bottom of the page
-  - git-authors
+
   # Enables use of Git submodules and larger code base
-  - monorepo
-  # For PDF rendering
-#  - with-pdf:
-#      author: SparkFun Electronics&#174;
-#      copyright: Copyright 2023 - SparkFun Electronics&#174;
-#      cover_subtitle: none
-#      cover_logo: img/sfe_logo_sm.png
-#      exclude_pages: [ "hard_copy", "single_page", "file_issue", "contribute" ]
-      # render_js: true
-      # headless_chrome_path: headless-chromium
-#      output_path: board_files/hookup_guide.pdf
+  - monorepo:
+      # Disables plugin on local builds
+      enabled: !ENV [CI, false]
 
 
 # Included Markdown extensions
 markdown_extensions:
+  # Adds support for syntax highlighting of code blocks
   - pymdownx.highlight:
       anchor_linenums: true
       line_spans: __span
+      pygments_lang_class: true
+
+  # Adds support for syntax highlighting of inline code blocks
   - pymdownx.inlinehilite
+
+  # Adds the ability to embed content from arbitrary files
   - pymdownx.snippets:
-      # base_path: ['./docs']
+      base_path: ['.', './docs']
       url_download: true
       url_max_size: 0
       url_timeout: 0
       url_request_headers: {}
-  - pymdownx.superfences
-  - pymdownx.details
+      dedent_subsections: True
+
+      # Adds support for a glossary of abbreviations
+      auto_append:
+        # - https://raw.githubusercontent.com/santaimpersonator/git-test/main/glossary-sparkfun.md
+        # - glossary-sparkfun.md
+        # - glossary-local.md
+
+  # Enables page previews
+  - material.extensions.preview:
+      configurations:
+        - targets:
+            exclude:
+              - resources.md
+              - troubleshooting_tips.md
+
+  # Allows embedding of code blocks in other elements
+  - pymdownx.superfences:
+      # Allows the use of diagrams
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+
+  # Allows the use of tabs in the document
   - pymdownx.tabbed:
       alternate_style: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
+
+  # Allows the use of Markup syntax
   - pymdownx.betterem:
       smart_enable: all
+
+  # Allows the use of in-text highlighting in Markdown syntax
   - pymdownx.mark
+  - pymdownx.critic
+
+  # Allows the use of superscript/subscript formatting in Markdown syntax
   - pymdownx.caret
+
+  # Allows the use of strikeout formatting in Markdown syntax
   - pymdownx.tilde
+
+  # Allows the use of keyboard button formatting in Markdown syntax
   - pymdownx.keys
+
+  # Allows the use of tables in Markdown syntax
   - tables
+
+  # Allows the use of admonition/call-out boxes
   - admonition
+
+  # Allows admonition extension to collapse the call-out boxes
+  - pymdownx.details
+
+  # Allows the use of Markdown syntax in HTML elements
   - md_in_html
+
+  # Allows the use of HTML syntax in Markdown elements
   - attr_list
+
+  # Allows the use of definition list formatting in Markdown syntax
+  - def_list
+
+  # Allows the use of footnotes
+  - footnotes
+
+  # Allows the use of abbreviations
+  - abbr
+
+  # Allows the use of bundled and custom icons and emojis
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
       options:
         custom_icons:
           - overrides/.icons
+
+  # Allows for the rendering of block and inline-block equations
   - pymdownx.arithmatex:
       generic: true
+
+  # Adds permalink icon to headers
   - toc:
       permalink: ''
       # Link: &#x1F517; 🔗
       # Chain: &#x26D3; ⛓
 
 
-
 extra:
   # Configures the hyperlink for the logo in the header
   homepage: https://www.sparkfun.com/
@@ -223,6 +352,8 @@ extra:
       link: https://www.facebook.com/SparkFun
     - icon: fontawesome/brands/x-twitter
       link: https://twitter.com/sparkfun
+    - icon: simple/discourse
+      link: https://community.sparkfun.com/
 
   # Configures Google Analytics
   analytics:
@@ -243,17 +374,42 @@ extra:
       - reject
 
 
-# Configures styling for PDF rendering and webpage layout
+# Configures styling for the webpage
 extra_css:
+  # SparkFun Customizations
   - stylesheet/extra.css
 
-# Enables support for rendering block and inline block equations through MathJax
+  # Enables support for KaTeX
+  # Leave disabled - causes issue when listing prices
+  # - https://unpkg.com/katex@0/dist/katex.min.css
+
+
+# Enables support for rendering block and inline block equations through MathJax and KaTeX
 extra_javascript:
-#  # Enables support for rendering block and inline block equations through MathJax
+  # Enables support for MathJax
   - javascript/mathjax.js
-  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  # - https://polyfill.io/v3/polyfill.min.js?features=es6
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
+  # Enables support for KaTeX
+  # Leave disabled - causes issue when listing prices
+  # - javascript/katex.js
+  # - https://unpkg.com/katex@0/dist/katex.min.js
+  # - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js
+
+
+# Configures webpage navigation
+
+# Excludes README.md files from being built as webpages
+exclude_docs: |
+  README.md
+
+# Pages that are built, but not in the navigation menu
+not_in_nav: |
+  index.md
+  print_view.md
+  favicon.ico
+
 # Configures webpage navigation
 nav:
   - Getting Started:

overrides/.icons/README.md

@@ -0,0 +1,13 @@
+.icons directory
+====================
+This folder should contain branding logos for the product documentation
+
+## General Images
+- `sfe.svg` - SparkFun flame logo
+- `kicad-primary.svg` - Full KiCad logo
+
+## Directory
+- `logo` - Other available logos
+
+## SVG Optimizer
+- [Remove meta data from svg](https://jakearchibald.github.io/svgomg/)