docs: switch from mkdocs to properdocs (#2946)

properdocs is a drop-in MkDocs fork by the original MkDocs maintainers.
The existing plugins (include-markdown, macros, intersphinx) and pymdown
extensions work unchanged; themes are unbundled, so the readthedocs
theme comes from properdocs-theme-readthedocs.

Assisted-by: ClaudeCode:claude-fable-5

properdocs.yml

@@ -0,0 +1,62 @@
+site_name: cibuildwheel
+docs_dir: docs
+theme:
+  name: readthedocs
+  highlightjs: true
+  hljs_languages:
+      - yaml
+  collapse_navigation: false
+  navigation_depth: 3
+  custom_dir: docs/theme_overrides
+repo_url: https://github.com/pypa/cibuildwheel
+edit_uri: edit/main/docs/
+
+extra_css:
+  - extra.css
+
+extra_javascript:
+  - extra.js
+
+
+nav:
+  - Home: index.md
+  - Guide:
+    - setup.md
+    - ci-services.md
+    - deliver-to-pypi.md
+    - faq.md
+    - cpp_standards.md
+  - Reference:
+    - options.md
+    - configuration.md
+    - platforms.md
+    - working-examples.md
+  - About:
+    - contributing.md
+    - changelog.md
+    - Source repository: https://github.com/pypa/cibuildwheel
+
+markdown_extensions:
+  - md_in_html
+  - toc:
+      permalink: True
+  - attr_list
+  - admonition
+  - pymdownx.magiclink:
+      repo_url_shortener: True
+  - pymdownx.highlight:
+      # use highlightjs - it's built-in to the theme
+      use_pygments: False
+  - pymdownx.superfences
+
+plugins:
+  - include-markdown
+  - search
+  - macros:
+      module_name: docs/main
+      j2_variable_start_string: «
+      j2_variable_end_string: »
+      on_error_fail: true
+      on_undefined: strict
+  - intersphinx:
+      project: cibuildwheel