mkdocs.yml

# Documentation page information
site_name: SparkFun Portability Shield Hookup Guide
site_description: A guide for getting started with the SparkFun Portability Shield
site_url: https://sparkfun.github.io/SparkFun_Portability_Shield
site_author: SparkFun Electronics

repo_url: https://github.com/sparkfun/SparkFun_Portability_Shield
repo_name: sparkfun/SparkFun_Portability_Shield

copyright:
  Copyright 2023 - <a href="https://www.sparkfun.com/" target="_blank" rel="noopener">SparkFun Electronics&#174;</a><br>
  <a href="https://goo.gl/maps/vkstCpQZW6jZMjzYA" target="_blank" rel="noopener">6333 Dry Creek Parkway, Niwot, Colorado 80503</a>

# 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


  # Icon in Browser Tab (must be square img - i.e. 32x32 pixels)
  favicon: assets/img/sfe_logo_sq.png


  # Page Font
  font:
    text: Roboto
    code: Roboto Mono
  

  # Features to Include (ref. theme documentation)
  features:
    # Enable copy button on code blocks
    - content.code.copy

    # Enable annotations in code blocks
    - content.code.annotate

    # Enables code selection button to link a specific section of a code block
    - content.code.select

    # Enable "view source" and "edit this page" buttons
    - content.action.edit
    # - content.action.view

    # Enable Navigation buttons in the footer (i.e. previous/next)
    - navigation.footer

    # Enables anchor tracking (updates page url with the section user is on)
    # i.e. https://docs.sparkfun.com/<page link>/#<sub-section>
    - navigation.tracking

    # 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
    - navigation.top

    # Renders path for page navigation at the top of the page (makes page navigation more mobile friendly)
    - navigation.path

    # Enables instant previews globally, for all internal links
    - navigation.instant.preview

  # Adds light/dark theme to the webpage
  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      primary: grey
      accent: red
      toggle:
        icon: material/brightness-auto
        name: Switch to dark mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      primary: grey
      accent: red
      scheme: default 
      toggle:
        icon: material/brightness-7
        name: Switch to system preference

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      primary: grey
      accent: red
      scheme: slate
      toggle:
        icon: material/weather-night
        name: Switch to light mode    


  # Configures icons
  icon:
    # Sets homepage icon
    logo: sfe-logo

    # Sets repo icon to GitHub icon
    repo: fontawesome/brands/github
    
    # Sets icons for "view source" (commented out) and "edit this page" buttons
    edit: material/file-document-edit-outline
    # view: material/file-code-outline

    # Admonition Icons (callout boxes)
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: simple/sparkfun
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16
      # Add custom admonitions
      github: simple/github
      arduino: simple/arduino
      python: simple/python
      code: fontawesome/regular/file-code
      terminal: octicons/terminal-16
      serial: fontawesome/solid/display
      hot: material/fire-alert
      # Permalink icon
      link: octicons/link-16


  # Adds overrides for icons, HTML, etc.
  custom_dir: overrides



# Included MkDocs plugins
# Add the installation of any new plugins to the ./github/workflows/mkdocs.yml file also
plugins:
  - search
  - redirects:
      redirect_maps:
          'index.md': 'introduction.md'


  # Enables improved security for external links
  - privacy:
      # 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/*

      # External links open in a new tab
      links_attr_map:
        target: _blank
      links_noopener: true
                
  # Add revision date
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
  # Add git committers at the bottom of the page
  - git-committers:
      repository: sparkfun/SparkFun_Portability_Shield
      branch: main
  # Add git authors at the 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: assets/img/sfe_logo_sm.png
  #     exclude_pages: [ "hard_copy", "single_page", "github/file_issue", "github/contribute" ]
  #     output_path: assets/board_files/hookup_guide.pdf



# Included Markdown extensions
markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite

    # Adds the ability to embed content from arbitrary files
  - pymdownx.snippets:
      base_path: ['.', './docs']
      url_download: true
      url_max_size: 0
      url_timeout: 0
      url_request_headers: {}
      dedent_subsections: True

      # Adds support for glossary of abbreviations
      auto_append:
        # - https://raw.githubusercontent.com/santaimpersonator/git-test/main/glossary-sparkfun.md
        - glossary-sparkfun.md
        - glossary-local.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 for collapsible admonitions
  - 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:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

  # Allows for 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


  # Configures social icons in the footer
  social:
    - icon: sfe-logo # simple/sparkfun
      link: https://www.sparkfun.com/products/26060
    - icon: fontawesome/brands/youtube
      link: https://www.youtube.com/sparkfun
    - icon: fontawesome/brands/instagram
      link: https://www.instagram.com/sparkfun
    - icon: fontawesome/brands/github
      link: https://www.github.com/sparkfun
    - icon: fontawesome/brands/facebook
      link: https://www.facebook.com/SparkFun
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/sparkfun
      link: /#__consent
      name: Change cookie settings

  # Configures Google Analytics
  analytics:
    provider: google
    property: G-7Y7EYCZVC1

  consent:
    cookies:
      analytics:
        name: Google Analytics
        checked: true
    title: Cookie consent
    description:
      We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.
    actions:
      - accept
      - manage 
      - reject



# Configures styling for PDF rendering and webpage layout
extra_css:
  - stylesheet/extra.css



# Enables support for rendering block and inline block equations through MathJax
extra_javascript:
  # Enables support for rendering block and inline block equations through MathJax
  - javascript/mathjax.js
  - https://polyfill.io/v3/polyfill.min.js?features=es6
  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.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 tabs
not_in_nav: |
  index.md
  print_view.md
  favicon.ico

# Configures webpage navigation
nav:
  - Hookup Guide: 
    - Introduction: introduction.md
    - Hardware Overview: hardware_overview.md
    - Hardware Assembly: hardware_assembly.md
#    - Software Setup: software_setup-arduino.md
    - Arduino Examples: arduino_example.md
  - Resources: resources.md
  - Support:
    - Troubleshooting: troubleshooting.md
    - Submit Issues: github/file_issue.md
    - Contribute: github/contribute.md