pwndbg/mkdocs.yml

# Make LSPs validate the mkdocs format
# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json

site_url: https://pwndbg.re/
site_name: Documentation
site_description: >-
    pwndbg (/paʊnˈdiˌbʌɡ/) is a GDB plug-in that makes debugging with GDB suck less, with a focus on features needed by low-level software developers, hardware hackers, reverse-engineers and exploit developers.

repo_name: pwndbg/pwndbg
repo_url: https://github.com/pwndbg/pwndbg/
edit_uri: edit/dev/docs/

theme:
  name: material
  favicon: assets/favicon.ico
  logo: assets/logo.png
  icon:
    # Edit button at the top of each page.
    edit: material/pencil-ruler
  font:
    text: Roboto
    code: Roboto Mono
  features:
    # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/
    # A button to copy code snippets.
    # - content.code.copy
    # Enable annotations in code blocks.
    - content.code.annotate
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
    # Use XHR instead of fully reloading the page when navigating around.
    - navigation.instant
    # Progress bar on page load for slow connections (>400ms).
    - navigation.instant.progress
    # Anchor tracking, updates the address bar with the active anchor.
    # - navigation.tracking
    # Show top-level sections in a horizontal header.
    - navigation.tabs
    # Stick the tabs while scrolling down.
    # - navigation.tabs.sticky
    # Expand sections in the navbar.
    - navigation.sections
    # Allow preceding index pages per section.
    - navigation.indexes
    # I don't understand what this does.
    # - toc.follow
    # Instead of putting the toc on the right, integrate it with the nav on the left.
    # - toc.integrate
    # A button that takes the user to the top of the page.
    - navigation.top
    # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
    # Press right arrow to accept search suggestion.
    - search.suggest
    # Highlight the search query on the chosen page.
    # - search.highlight
    # Add a "share" button to copy a link to the search query.
    - search.share
    # https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
    # Adds an edit button to every page that links to the repository.
    # - content.action.edit
    # Extra
    # Sync the content tab selection across the whole site (based on label).
    - content.tabs.link
  palette:
    scheme: slate
    primary: black
    accent: purple

plugins:
  - blog
  - search:
      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
  - minify:
      minify_html: true

  # Used to reference source code from markdown files
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          # https://mkdocstrings.github.io/python/usage/
          load_external_modules: false
          paths: ["pwndbg"]
          options:
            # https://mkdocstrings.github.io/python/usage/configuration/general/
            # Allow importing modules to improve doc generation.
            # We have to disable this since many modules can't be imported easily
            # as they require gdb/lldb to be running.
            allow_inspection: false
            backlinks: tree
            show_source: false
            # Show the base classes of a class.
            show_bases: true
            extensions:
              # https://mkdocstrings.github.io/griffe/extensions/
              # E.g. converts union types from Union[A, B] to A | B.
              - griffe_modernized_annotations
            # https://mkdocstrings.github.io/python/usage/configuration/headings/
            heading_level: 1
            parameter_headings: false
            show_root_heading: true
            show_root_toc_entry: true
            show_root_full_path: false
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            # https://mkdocstrings.github.io/python/usage/configuration/members
            inherited_members: true
            members_order: source
            # WARN: Enabling this gives very flaky, hard-to-diagnose errors! Don't.
            # filters: public
            group_by_category: true
            summary: true
            # https://mkdocstrings.github.io/python/usage/configuration/docstrings/
            docstring_style: google
            docstring_section_style: list
            merge_init_into_class: true
            relative_crossrefs: true
            scoped_crossrefs: true
            show_if_no_docstring: true
            # All show_docstring_* options are enabled by default.
            # https://mkdocstrings.github.io/python/usage/configuration/signatures/
            line_length: 80
            modernize_annotations: true
            show_signature: true
            separate_signature: true
            show_signature_annotations: true
            show_overloads: true
            signature_crossrefs: true
            docstring_options:
              # https://mkdocstrings.github.io/griffe/reference/docstrings/#google-options
              ignore_init_summary: true
              trim_doctest_flags: true
              warn_unknown_params: true

  # Generate the whole Source page magically (hooks into mkdocstrings)
  - api-autonav:
      modules: ["pwndbg"]
      nav_section_title: "Source"

  # Documentation versioning
  - mike:
      css_dir: stylesheets
      version_selector: true
      canonical_version: stable

  # Fine-grained nav control
  - awesome-nav:

  - rss:
      # https://squidfunk.github.io/mkdocs-material/tutorials/blogs/engage/#rss-feeds
      # https://guts.github.io/mkdocs-rss-plugin/configuration/#plugin-options
      feed_title: "pwndbg Blog"
      # Image doesn't support relative paths :(.
      image: https://pwndbg.re/assets/favicon.ico
      match_path: blog/posts/.*
      date_from_meta:
        as_creation: date
      categories:
        - categories
        - tags

# Theme specific template values.
extra:
  # https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/
  # The icons in the footer.
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/pwndbg
    - icon: fontawesome/brands/python
      link: https://pypi.org/project/pwndbg/
    - icon: fontawesome/brands/discord
      link: https://discord.gg/x47DssnGwm
  # Set to false to hide the "Made with Material for MkDocs" text :(.
  generator: true
  # material integration with mike (doc versioning)
  version:
    provider: mike

extra_css:
  - stylesheets/extra.css
  - stylesheets/mkdocstrings.css

extra_javascript:
  - js/prompt-highlighter.js

markdown_extensions:
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - toc:
      permalink: "¤"
      toc_depth: 3
  - tables
  # https://facelessuser.github.io/pymdown-extensions/
  # Officially supported are:
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/
  # Not enabled from the list^ : arithmatex, critic
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.blocks.caption
  - pymdownx.caret
  - pymdownx.mark
  - pymdownx.tilde
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      # Perform highlighting at build time rather than client side.
      use_pygments: true
      # Don't annotate the used language above a code-block. In pwndbg it's obvious.
      auto_title: false
      linenums: false
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.smartsymbols
  - pymdownx.snippets
  - pymdownx.superfences:
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tabbed:
      # Better on mobile.
      alternate_style: true
      # Nicer looking anchor links.
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  # Not officially supported:
  - pymdownx.magiclink:
      repo_url_shortener: true
      repo_url_shorthand: true
      provider: github
      user: pwndbg
      repo: pwndbg
  - pymdownx.tasklist
# We intentionally do not include `nav:` so that it gets autogenerated using
# the folder structure. See also docs/.nav.yml