# Site configuration for the UNICADO homepage
# Copyright (c) UNICADO 2023
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.

# === General site meta data ===
site_name: UNICADO                        # The name of the site, displayed in the header.
repo_url: https://git.rwth-aachen.de/unicado/unicado-package  # Link to the Git repository, will appear in the header.
repo_name: UNICADO Repository             # Name for the Git repository link in the header.

# === Site configuration ===
markdown_extensions:
  - attr_list                             # Allows adding HTML attributes to Markdown elements (like classes).
  - admonition                            # Enables note/warning/admonition boxes with custom styling.
  - md_in_html                            # Allows writing Markdown inside HTML tags for flexibility.
  - toc:                                  # Adds a table of contents (ToC) for each page.
      permalink: '#'                      # Adds a clickable '#' for each ToC heading, allowing direct links.
  - pymdownx.tabbed:                      # Enables tabbed content blocks, allowing content to be organized in tabs.
      alternate_style: true               # Uses an alternate style for tabbed blocks.
  - pymdownx.emoji:                       # Adds support for emojis using the Material theme’s emoji set.
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:                   # Adds code syntax highlighting with custom line anchors.
      anchor_linenums: true               # Makes line numbers clickable in code blocks.
      line_spans: __span                  # Adds spans around lines for custom styling.
      pygments_lang_class: true           # Adds language class to highlighted code for styling consistency.
  - pymdownx.details                      # Enables collapsible details/summary blocks for content hiding/showing.
  - pymdownx.superfences                  # Adds advanced fence syntax for blocks like code or tabs.
  - pymdownx.inlinehilite                 # Allows inline code highlighting within text.
  - pymdownx.snippets                     # Enables code snippets for reusing code blocks across pages.
  - pymdownx.critic                       # Adds Critic Markup support for collaborative editing.
  - pymdownx.caret                        # Adds support for superscript text with a caret.
  - pymdownx.keys                         # Adds special styling for keyboard key indicators.
  - pymdownx.mark                         # Adds highlighting functionality for text.
  - pymdownx.tilde                        # Enables strikethrough formatting.

# Additional JavaScript files to include for rendering mathematical notation
extra_javascript:
  - assets/javascripts/katex.js           # Local KaTeX script.
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.js  # CDN KaTeX script (same as local but hosted externally).
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/contrib/auto-render.min.js  # KaTeX auto-render script (converts Latex syntax in formatted math).

# Additional CSS files to include for styling of website and mathematical notations (font, size etc.)
extra_css:
  - assets/css/unicado.css                # Custom CSS for styling the UNICADO site.
  - https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.7/katex.min.css  # CSS for KaTeX math rendering.

# === Plugins ===
plugins:
  - glightbox                             # Plugin for lightbox-style image and content viewing.

# === Theme configuration ===
theme:
  name: material                          # Specifies the theme name (alternatives: material, mkdocs, readthedocs).
  favicon: assets/favicon.png             # Path to the favicon image displayed in the browser tab (same as logo).
  logo: assets/images/logos/unicado-icon.png  # Path to the UNICADO logo displayed in the header.
  
  # Theme colors configuration
  palette:
    scheme: slate                         # Sets a dark theme style.
    primary: blue grey                    # Main color of the theme (used for buttons, links, etc.).
    accent: red                          # Accent color for highlights.

  # Feature configurations for navigation and ToC behavior
  features:
    - navigation.instant                  # Enables instant navigation between pages (no reload).
    - navigation.tabs                     # Adds navigation tabs for each main section in `nav`.
    - navigation.path                     # Shows the navigation path/breadcrumbs.
    - toc.follow                          # Highlights the current section in the ToC as you scroll.
    - navigation.footer                   # Adds navigation links in the footer.

  # Additional links (social) to display in the header
  extra:
    social:
      - icon: fontawesome/brands/github   # Icon for the GitHub link (uses FontAwesome icon set).
        link: https://git.rwth-aachen.de/unicado/unicado-package  # URL for the Git repository.
        name: "Unicado Repository"        # Name displayed when hovering over the repository icon.

# === Navigation Menu ===
nav:                                      # Customizes the main navigation structure of the site.
  - Home: 'index.md'                      # Main page of the site.
  - Download:                             # Top-level navigation item for "Download".
      - Installation: 'getting-started/installation.md'  # Link to the installation page.
      - Cleared for Take-Off: 'getting-started/takeoff.md'  # Link to the takeoff/getting started page.
  - Documentation:                        # Top-level item for documentation.
      - Overview: 'modules/overview.md'   # Overview of modules.
      - Aircraft Design:                  # Subsection for Aircraft Design.
          - 'modules/sizing.md'           # Link to sizing module page.
          - 'modules/analysis.md'         # Link to analysis module page.
      - Libraries: 'modules/libraries.md' # Link to libraries overview.
      - Utilities: 'modules/additional-software.md'  # Link to additional software page.
      - Workflow: 'workflow.md'           # Link to the workflow page.
  - Get involved:                         # Top-level item for contributions and development.
      - How to Contribute:                # Subsection for contribution guidelines.
          - Basics: 'developer/contribute.md'
          - Merge Requests: 'developer/merge-request.md'
          - Review Merge Requests: 'developer/review-merge-request.md'
      - Build Instructions:
          - Prerequisites:
              - Windows: 'developer/build-environment/windows.md'
              - Linux: 'developer/build-environment/linux.md'
              - MacOS: 'developer/build-environment/macos.md'
              - MSYS2/MinGW (deprecated): 'developer/build-environment/mingw.md'
          - Get Source Code: 'developer/get-source-code.md'
          - Build:
              - C++: 'developer/build/cpp.md'
              - Python: 'developer/build/python.md'
          - Include libraries: 'developer/including-libraries.md'
          - CMake Presets: 'developer/cmake-presets.md'
      - Testing Guidelines: 'developer/testing.md'
      - Release Package: 'developer/release-package.md'
      - Style Guide:
          - C++: 'developer/style/cpp.md'
          - Python: 'developer/style/python.md'
      - IDE Setup: 'developer/ide-setup.md'

  - About:                                # Top-level item for general site information.
      - License: 'license.md'             # Link to license information.
      - Contact: 'contact.md'             # Link to contact page.
      - Partners: 'partners.md'           # Link to partners page.
  - Impressum: 'impressum.md'             # Link to impressum/legal page.