MkDocs_MiSTer/mkdocs.yml

site_name: MiSTer FPGA Documentation
site_url: https://mister-devel.github.io/MkDocs_MiSTer/
site_author: Kevin Coleman
site_description: >-
  MiSTer FPGA is an open source project that aims to recreate various classic computers, game consoles, and arcade machines, using modern hardware.
copyright: Copyright © 2022-2025 MiSTer FPGA

repo_name: MkDocs_MiSTer
repo_url: https://github.com/MiSTer-devel/MkDocs_MiSTer/
edit_uri: edit/main/docs/

theme:
  palette:
    # Dark Mode
    - scheme: MiSTer-Dark
      toggle:
        icon: material/brightness-4
        name: Switch to Dark mode
    # Light Mode
    - scheme: MiSTer-Light
      toggle:
        icon: material/brightness-7
        name: Switch to Light mode

  name: material
  favicon: assets/8-bit_mister_kun_fullcolor.svg
  logo: assets/mister_kun_bw.svg
  font:
    text: Roboto
    code: Source Code Pro
  features:
    # Highlight search terms when user searches for things
    - search.highlight
    # Offer most likely search result as a suggestion
    - search.suggest
    # Update url with the active anchor as highlighted in ToC
    - navigation.tracking
    # Enable Edit on Github Button (needed after version 9)
    - content.action.edit
  # Folder for css and page overrides
  custom_dir: overrides


plugins:
# Explicitly call out search ahead of time, because if you use other plugins this has to be done.
  - search:
    # Only English for now
      lang: en
  # https://squidfunk.github.io/mkdocs-material/tutorials/social/basic/
  - social
  # mkdocs-rss-plugin
  # https://MiSTer-devel.github.io/MkDocs_MiSTer/feed_rss_updated.xml
  # https://MiSTer-devel.github.io/MkDocs_MiSTer/feed_rss_created.xml
  - rss:
      image: assets/mister_kun_bw.svg
  # Permits the use of embedded videos
  - ffc-mkdocs-video:
      css_style:
        width: 100%;
        height: 100%;
  # Adds date/time stamp to page when updated according to git history.
  - git-revision-date-localized
  # Makes things load faster at the cost of a little extra build time
  - minify:
      minify_html: true


# Customization
extra:
  # Subject to change later when incorporated into the project, potentially https://docs.misterfpga.org/
  homepage: https://MiSTer-devel.github.io/MkDocs_MiSTer/
  # Placeholder for analytics configuration, modify values and uncomment when ready
  # analytics:
  #   provider: google
  #   property: !ENV GOOGLE_ANALYTICS_KEY
  social:
    - icon: twitter
      link: https://twitter.com/MiSTerFPGABot/
    - icon: discord
      link: https://discord.com/invite/misterfpga/
    - icon: github
      link: https://github.com/MiSTer-devel/
    - icon: forum
      link: https://misterfpga.org/


nav:
  # Only the logo and brief summary of what the project is about
  - Home: index.md

  # Setup section is to remain very stable and simple
  - First-time Setup:
    - Requirements: setup/requirements.md
    - Setup MicroSD Card: setup/software.md
    - Running the Updater: setup/updater.md
    - Define Your Gamepad: setup/controller.md
    - Transferring Games: setup/games.md
    - Play a Game: setup/play.md

  # Just some basics things to go over. Slightly more advanced than the setup section above
  - The Basics:
    - FAQ: basics/faq.md
    - Troubleshooting: basics/troubleshooting.md
    - Game Saves: basics/saves.md
    - Addon Boards: basics/addons.md
    - Cases: basics/case.md
    - Hotkeys: basics/hotkey.md
    - Controllers: basics/input.md
    - Keyboards: basics/keyboard.md
    - WiFi: basics/wifi.md
    - Bluetooth: basics/bluetooth.md
    - Video Configuration: basics/video.md
    - CD-based ROMs: basics/cd.md
    - Links: basics/links.md

  # General core information, not a full replacement for the core Readme's however
  - Cores:
    - What Is a Core: cores/what.md
    # Just a good place to show off special features of some cores, to get people started.
    - Common Core Features:
      - Cheats: cores/features/cheats.md
      - RTC Support: cores/features/rtcsupport.md
    - Core Highlights:
      - PSX: cores/highlights/psx.md
      - SNES: cores/highlights/snes.md
      - NES: cores/highlights/nes.md
      - TurboGrafx-16: cores/highlights/tgfx16.md
      - Genesis: cores/highlights/genesis.md
      - MegaCD: cores/highlights/megacd.md
      - Saturn: cores/highlights/saturn.md
      - Game Boy 2 Player: cores/highlights/gb2p.md
    - Console Cores: cores/console.md
    - Computer Cores: cores/computer.md
    - Arcade Cores: cores/arcade.md
    - Other Cores: cores/other.md
    - Core Paths: cores/paths.md

  # More advanced configuration options. Anything not basic or not simple essentials, dump here.
  - Advanced Configuration:
    - Video Modes: advanced/videomodes.md
    - Video Scaling: advanced/videoscaling.md
    - Add-On Boards:
      - RTC Board: advanced/rtc.md
    - Networking:
      - Advanced Networking: advanced/network.md
      - Computer Core Networking: advanced/computer.md
    - CRT Displays:
      - CRT Configuration Table: advanced/crttable.md
      - Using Your CRT With MiSTer: advanced/crt.md
      - Direct Video Adapter: advanced/directvideo.md
      - Core Default Resolutions: advanced/nativeres.md
    - Audio Filters: advanced/audio.md
    - MIDI Features: advanced/midi.md
    - Multi-Button Mapping: advanced/multibutton.md
    - DIY 2-Player Arcade: advanced/diy2parcade.md
    - INI Settings: advanced/ini.md
    - Lag Explained: advanced/lag.md
    - MGL Files: advanced/mgl.md
    - Console Connection: advanced/console.md

  # Developer reference. This is going to mostly mirror what is up on Github wiki already.
  - Developer Reference:
    - Compiling for MiSTer: developer/mistercompile.md
    - Porting Cores: developer/porting.md
    - Core Configuration String: developer/conf_str.md
    - Top-level of Cores:
      - overview of emu module: developer/emu.md
      - sys - hps_io: developer/hps_io.md
      - sys - video_freak: developer/video_freak.md
      - sys - video_mixer: developer/video_mixer.md
      - sys - arcade_video: developer/arcade_video.md
    - Useful Snippets: developer/snippets.md
    - Savestates: developer/savestates.md
    - Core Names: developer/corenames.md
    - MRA Setnames: developer/mrasetnames.md
    - Arcade ROMS and MRA Files: developer/mra.md
    - Debugging (USB Blaster): developer/debugging.md
    - Core Components Where Used: developer/component.md
    - Developer Journeys:
      - Analog Simulation: developer/analogsim.md
      - Head On Sound PCB Implementation: developer/headonsoundpcb.md
    - Template Core: https://github.com/MiSTer-devel/Template_MiSTer
    - Useful Links: developer/links.md
    - Tips and Guidelines: developer/principles.md

  # Fun guide that shows users how to edit the documentation site
  - Editing These Docs: editing.md


markdown_extensions:
  # https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
  - pymdownx.highlight:
      anchor_linenums: true
  # https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
  - pymdownx.inlinehilite
  # https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
  - pymdownx.snippets
  # https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
  - pymdownx.superfences
  # https://facelessuser.github.io/pymdown-extensions/extensions/keys/
  - pymdownx.keys:
      camel_case: true
  # https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  # https://squidfunk.github.io/mkdocs-material/reference/images/
  - attr_list
  # https://python-markdown.github.io/extensions/md_in_html/
  - md_in_html
  - footnotes
  - admonition
  - pymdownx.details

extra_css:
  - stylesheets/extra.css

extra_javascript:
  - javascripts/extra.js