Fixing all broken links, pymarkdown (#1052)

Future-House · dmcgrath19 · Aug 6, 2025 · Aug 6, 2025 · Aug 6, 2025 · Aug 7, 2025
commit 948423f0f8836254e8137ae4a1ae46c5007a23e3
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -23,7 +23,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.2
+    rev: v0.12.8
     hooks:
       - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix]
@@ -54,11 +54,11 @@ repos:
     hooks:
       - id: check-mailmap
   - repo: https://github.com/henryiii/validate-pyproject-schema-store
-    rev: 2025.06.23
+    rev: 2025.08.07
     hooks:
       - id: validate-pyproject
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.7.19
+    rev: 0.8.6
     hooks:
       - id: uv-lock
   - repo: https://github.com/adamchainz/blacken-docs
@@ -71,11 +71,10 @@ repos:
     hooks:
       - id: nb-clean
         args: [--preserve-cell-outputs, --remove-empty-cells]
-  - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.45.0
+  - repo: https://github.com/jackdewinter/pymarkdown
+    rev: v0.9.31
     hooks:
-      - id: markdownlint
-        args: [--config=pyproject.toml, --configPointer=/tool/markdownlint]
+      - id: pymarkdown
         exclude: docs/tutorials/
   - repo: https://github.com/mwouts/jupytext
     rev: v1.17.2
@@ -89,7 +88,7 @@ repos:
     hooks:
       - id: markdown-toc-creator
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.16.1
+    rev: v1.17.1
     hooks:
       - id: mypy
         args: [--pretty, --ignore-missing-imports]

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # PaperQA2
 
-[![GitHub](https://img.shields.io/badge/github-%23121011.svg?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa)
+<!-- pyml disable-num-lines 6 line-length -->
+
+[![GitHub](https://img.shields.io/badge/GitHub-black?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa)
 [![PyPI version](https://badge.fury.io/py/paper-qa.svg)](https://badge.fury.io/py/paper-qa)
 [![tests](https://github.com/Future-House/paper-qa/actions/workflows/tests.yml/badge.svg)](https://github.com/Future-House/paper-qa)
 ![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)
@@ -308,7 +310,7 @@ For each OpenAI tier, a pre-built setting exists to limit usage.
 pqa --settings 'tier1_limits' ask 'What is PaperQA2?'
 ```
 
-This will limit your system to use the [tier1_limits](paperqa/configs/tier1_limits.json),
+This will limit your system to use the [tier1_limits](src/paperqa/configs/tier1_limits.json),
 and slow down your queries to accommodate.
 
 You can also specify them manually with any rate limit string that matches the specification in

diff --git a/docs/tutorials/settings_tutorial.ipynb b/docs/tutorials/settings_tutorial.ipynb
@@ -96,9 +96,9 @@
    "metadata": {},
    "source": [
     "The `Settings` class is used to configure the PaperQA settings.\n",
-    "Official documentation can be found [here](https://github.com/Future-House/paper-qa?tab=readme-ov-file#settings-cheatsheet) and the open source code can be found [here](https://github.com/Future-House/paper-qa/blob/main/paperqa/settings.py).\n",
+    "Official documentation can be found [here](https://github.com/Future-House/paper-qa?tab=readme-ov-file#settings-cheatsheet) and the open source code can be found [here](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/settings.py).\n",
     "\n",
-    "Here is a basic example of how to use the `Settings` class. We will be unnecessarily verbose for the sake of clarity. Please notice that most of the settings are optional and the defaults are good for most cases. Refer to the [descriptions of each setting](https://github.com/Future-House/paper-qa/blob/main/paperqa/settings.py) for more information.\n",
+    "Here is a basic example of how to use the `Settings` class. We will be unnecessarily verbose for the sake of clarity. Please notice that most of the settings are optional and the defaults are good for most cases. Refer to the [descriptions of each setting](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/settings.py) for more information.\n",
     "\n",
     "Within this `Settings` object, I'd like to discuss specifically how the llms are configured and how `paperqa` looks for papers.\n",
     "\n",

diff --git a/docs/tutorials/settings_tutorial.md b/docs/tutorials/settings_tutorial.md
@@ -75,9 +75,9 @@ async with aiohttp.ClientSession() as session, session.get(url, timeout=60) as r
 ```
 
 The `Settings` class is used to configure the PaperQA settings.
-Official documentation can be found [here](https://github.com/Future-House/paper-qa?tab=readme-ov-file#settings-cheatsheet) and the open source code can be found [here](https://github.com/Future-House/paper-qa/blob/main/paperqa/settings.py).
+Official documentation can be found [here](https://github.com/Future-House/paper-qa?tab=readme-ov-file#settings-cheatsheet) and the open source code can be found [here](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/settings.py).
 
-Here is a basic example of how to use the `Settings` class. We will be unnecessarily verbose for the sake of clarity. Please notice that most of the settings are optional and the defaults are good for most cases. Refer to the [descriptions of each setting](https://github.com/Future-House/paper-qa/blob/main/paperqa/settings.py) for more information.
+Here is a basic example of how to use the `Settings` class. We will be unnecessarily verbose for the sake of clarity. Please notice that most of the settings are optional and the defaults are good for most cases. Refer to the [descriptions of each setting](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/settings.py) for more information.
 
 Within this `Settings` object, I'd like to discuss specifically how the llms are configured and how `paperqa` looks for papers.
 

diff --git a/docs/tutorials/where_do_I_get_papers.md b/docs/tutorials/where_do_I_get_papers.md
@@ -59,7 +59,7 @@ You can also manually drag-and-drop PDFs onto each reference.
 To download papers, you need to get an API key for your account.
 
 1. Get your library ID, and set it as the environment variable `ZOTERO_USER_ID`.
-   - For personal libraries, this ID is given [here](https://www.zotero.org/settings/keys) at the part "_Your userID for use in API calls is XXXXXX_".
+   - For personal libraries, this ID is given [here](https://www.zotero.org/settings/security#applications) at the part "_Your userID for use in API calls is XXXXXX_".
    - For group libraries, go to your group page `https://www.zotero.org/groups/groupname`, and hover over the settings link. The ID is the integer after /groups/. (_h/t pyzotero!_)
 2. Create a new API key [here](https://www.zotero.org/settings/keys/new) and set it as the environment variable `ZOTERO_API_KEY`.
    - The key will need read access to the library.

diff --git a/packages/paper-qa-pymupdf/README.md b/packages/paper-qa-pymupdf/README.md
@@ -1,6 +1,8 @@
 # paper-qa-pymupdf
 
-[![GitHub](https://img.shields.io/badge/github-%23121011.svg?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa/tree/main/packages/paper-qa-pymupdf)
+<!-- pyml disable-num-lines 6 line-length -->
+
+[![GitHub](https://img.shields.io/badge/GitHub-black?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa/tree/main/packages/paper-qa-pymupdf)
 [![PyPI version](https://badge.fury.io/py/paper-qa-pymupdf.svg)](https://badge.fury.io/py/paper-qa-pymupdf)
 [![tests](https://github.com/Future-House/paper-qa/actions/workflows/tests.yml/badge.svg)](https://github.com/Future-House/paper-qa)
 ![License](https://img.shields.io/badge/license-AGPLv3-blue.svg)

diff --git a/packages/paper-qa-pypdf/README.md b/packages/paper-qa-pypdf/README.md
@@ -1,6 +1,8 @@
 # paper-qa-pypdf
 
-[![GitHub](https://img.shields.io/badge/github-%23121011.svg?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa/tree/main/packages/paper-qa-pypdf)
+<!-- pyml disable-num-lines 6 line-length -->
+
+[![GitHub](https://img.shields.io/badge/GitHub-black?logo=github&logoColor=white)](https://github.com/Future-House/paper-qa/tree/main/packages/paper-qa-pypdf)
 [![PyPI version](https://badge.fury.io/py/paper-qa-pypdf.svg)](https://badge.fury.io/py/paper-qa-pypdf)
 [![tests](https://github.com/Future-House/paper-qa/actions/workflows/tests.yml/badge.svg)](https://github.com/Future-House/paper-qa)
 ![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)

diff --git a/pyproject.toml b/pyproject.toml
@@ -127,15 +127,6 @@ skip = [
     "tests/stub_data/*",
 ]
 
-[tool.markdownlint]
-no-inline-html = false
-
-[tool.markdownlint.line-length]
-code_block_line_length = 88  # Match ruff line-length
-line_length = 120  # Match ruff max-doc-length
-stern = true
-tables = false
-
 [tool.mypy]
 # Type-checks the interior of functions without type annotations.
 check_untyped_defs = true
@@ -305,6 +296,16 @@ score = false
 # Minimum lines number of a similarity.
 min-similarity-lines = 12
 
+[tool.pymarkdown]
+plugins.line-length.code_block_line_length = 88  # Match ruff line-length
+plugins.line-length.enabled = true
+plugins.line-length.line_length = 120  # Match ruff max-doc-length
+plugins.line-length.stern = true
+plugins.line-length.tables = false
+plugins.no-duplicate-heading.siblings_only = true  # GitHub appends -X for duplicated headings
+plugins.no-emphasis-as-heading.enabled = false
+plugins.no-inline-html.enabled = false
+
 [tool.pytest.ini_options]
 # Add the specified OPTS to the set of command line arguments as if they had been
 # specified by the user.