# 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

# https://github.com/mkdocstrings/mkdocstrings/issues/817#issuecomment-3927886394

returns_multiple_items: false

# 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