Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

docs: rewrite out-of-docs links on the element tree instead of the raw Markdown

Aperta
  • Qualcosa non va?
#19 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
45/100
Tipo di issue
Refactoring
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
markdown, python
Ambito
documentation, tooling

Direzione di ricerca

Start with dokimi/scripts/docs/hooks.py: the regex rewrite in on_page_markdown and the _REFDEF pattern are what gets replaced, and on_config is where a Markdown treeprocessor would be registered. Read how mkdocs' own relpath treeprocessor orders itself so the new one runs before it. Done means tests/test_docs_hooks.py covers links inside fenced and inline code, a link with a title, an angle-bracket link, a reference-style image, and a raw <a href> case, and each passes with the old behaviour kept for in-docs/ and missing targets.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Follow-up to #6 (review comment https://github.com/intel/dokimi/pull/6#discussion_r4270668787).

dokimi/scripts/docs/hooks.py points links that leave docs/ at the file on GitHub. It does that with regexes over the raw Markdown in on_page_markdown, which has known gaps. The current docs don't hit any of them: the hook changes exactly the real out-of-docs links. But any of them can start to matter as the docs change.

Gaps of the regex approach

  • Code is rewritten too. The regexes also match inside fenced, indented and inline code. A [x](../dokimi/cli.py) in a code sample becomes a GitHub URL on the rendered page, and _REFDEF matches a [tool]: ../x line inside a TOML fence.
  • Titles and angle brackets are missed. [x](../a "title") and [x](<../a>) are not rewritten. That is safe, because they then fail --strict, but they can't be used.
  • Raw HTML is missed. A raw <a href="../x"> or <img src="../x"> is not rewritten, and mkdocs doesn't validate raw HTML, so it would 404 on the site without a warning.
  • Images only partly. #6 gives inline images (![](../x.png)) a raw/ URL. An image written through a reference definition (![x][id] with [id]: ../x.png) still gets blob/, which is an HTML page.

Proposed fix

Rewrite on the element tree instead of the text:

  • Register a Markdown treeprocessor from on_config, with a priority above mkdocs' own relpath treeprocessor (0), so it sees the links before mkdocs resolves them.
  • Rewrite a[href] and img[src]: blob/ (or tree/ for a directory) for links, raw/ for images.
  • Keep the behaviour #6 added: leave targets inside docs/ and missing targets alone, so mkdocs' "not found" warning still fails --strict, and warn, naming the page, on a target outside the repository.

Code is then never touched, titles and angle brackets are handled by the parser, and reference-style images get raw/ too. Raw HTML stays out of reach of a treeprocessor (it is stashed as a placeholder), so it would need either a postprocessor over the stashed HTML or a check that fails on a relative href/src in raw HTML.

Tests

Extend tests/test_docs_hooks.py with links in a fence, in inline code, with a title, in angle brackets, a reference-style image, and a raw <a href>.

Lingua principale
Python
Stelle
8
Fork
7
Merge medio
1g 55m
PR unite (30g)
126

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di intel/dokimi

Tutte le issue di intel/dokimi

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.