Fix broken anchor links #2091

EthanHeilman commented at 1:09 AM on January 24, 2026: contributor

At some point github changed how anchor links work. Currently anchor links using the double square bracket format require that the anchor be prepended with user-content-.

This means that the following link used to work, but doesn't today

 [[bip-0341.mediawiki#design|BIP341]]

The link that works today would be

[[bip-0341.mediawiki#user-content-design|BIP341]]

The link still resolves to the page, but just not the anchor so I suspect no one noticed.

In addition to this it appears that in the past github anchors could have spaces or punction, but that is no longer valid. Spaces are replaced with _ and punction appears to be not included in the anchor.

I fixed this for BIP 0342, BIP 0022, BIP 0023, but it impacts a good chunk of BIPs. If you want I can change this PR to fix for all the BIPs, but I didn't want to put in the time to do that in case an editor wanted to make these changes themselves.

If this PR isn't useful or the project isn't interested in fixing this very minor linking issue. Feel free to close this PR.

murchandamus added the label Proposed BIP modification on Jan 25, 2026

murchandamus added the label Bug fix on Jan 25, 2026

murchandamus commented at 11:48 PM on January 25, 2026: member

I was able to verify the issue (original links are broken, new link works in the edited file). Will follow-up in the following days.

murchandamus requested review from murchandamus on Jan 25, 2026

in bip-0342.mediawiki:108 in f87a5a31ec

 103 | @@ -104,8 +104,8 @@ The following rules apply to <code>OP_CHECKSIG</code>, <code>OP_CHECKSIGVERIFY</
 104 |  
 105 |  ===Common Signature Message Extension===
 106 |  
 107 | -We define the tapscript message extension ''ext'' to [[bip-0341.mediawiki#common-signature-message|BIP341 Common Signature Message]], indicated by ''ext_flag = 1'':
 108 | -* ''tapleaf_hash'' (32): the tapleaf hash as defined in [[bip-0341.mediawiki#design|BIP341]]

murchandamus commented at 11:20 PM on January 26, 2026:

The two existing links here appear to work fine for me, as does the one in line 116.

in bip-0022.mediawiki:27 in f87a5a31ec

  23 | @@ -24,15 +24,15 @@ This BIP is licensed under the BSD 2-clause license.
  24 |  
  25 |  A JSON-RPC method is defined, called "getblocktemplate".
  26 |  It accepts exactly one argument, which MUST be an Object of request parameters.
  27 | -If the request parameters include a "mode" key, that is used to explicitly select between the default "template" request or a [[bip-0023.mediawiki#Block Proposal|"proposal"]].
  28 | +If the request parameters include a "mode" key, that is used to explicitly select between the default "template" request or a [[bip-0023.mediawiki#user-content-Block_Proposal|"proposal"]].

murchandamus commented at 11:32 PM on January 26, 2026:

Looking a bit more into this, I think there is a better way.

Inserting user-content- before the anchor into link [[bip-0023.mediawiki#user-content-Block_Proposal|"bla"]] actually causes the link to open too low in the page for me (either on Firefox and Brave).

When the link is sanitized by lowercasing all words and replacing spaces with hyphens instead, [[bip-0023.mediawiki#block-proposal|"bla"]], it jumps to the right spot just above the targeted header.

Therefore, I would suggest to sanitze the links instead as follows:

If the request parameters include a "mode" key, that is used to explicitly select between the default "template" request or a [[bip-0023.mediawiki#block-proposal|"proposal"]].

jonatack commented at 8:23 PM on May 5, 2026:

Therefore, I would suggest to sanitze the links instead as follows

I like this approach better -- it is cleaner and is more what am used to seeing.

jonatack commented at 8:35 PM on May 5, 2026:

Inserting user-content- before the anchor into link [[bip-0023.mediawiki#user-content-Block_Proposal|"bla"]] actually causes the link to open too low in the page for me (either on Firefox and Brave).

Same for me on Firefox 150.

in bip-0022.mediawiki:35 in f87a5a31ec

  32 |  !colspan=4|template request
  33 |  |-
  34 |  ! Key !! Required !! Type !! Description
  35 |  |-
  36 | -| capabilities || No || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#Block Proposal|"proposal"]], [[bip-0023.mediawiki#Logical Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#Mutations|mutations]]
  37 | +| capabilities || No || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#user-content-Block_Proposal|"proposal"]], [[bip-0023.mediawiki#user-content-Logical_Services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#user-content-Mutations|mutations]]

murchandamus commented at 11:33 PM on January 26, 2026:

| capabilities || No || Array of Strings || SHOULD contain a list of the following, to indicate client-side support: [[#Optional: Long Polling|"longpoll"]], "coinbasetxn", "coinbasevalue", [[bip-0023.mediawiki#block-proposal|"proposal"]], [[bip-0023.mediawiki#logical-services|"serverlist"]], "workid", and any of the [[bip-0023.mediawiki#mutations|mutations]]

murchandamus commented at 11:41 PM on January 26, 2026:

Could you please also fix the anchors below in the same document on line 58-68?

in bip-0023.mediawiki:34 in f87a5a31ec

  34 | -* [[#Mutations|BIP 23 Mutation "time/increment"]] (only required for servers)
  35 | +* [[bip-0022.mediawiki#user-content-Optional_Long_Polling|BIP 22 Long Polling]]
  36 | +* [[#user-content-Basic_Pool_Extensions|BIP 23 Basic Pool Extensions]]
  37 | +* [[#user-content-Mutations|BIP 23 Mutation "coinbase/append"]]
  38 | +* [[#user-content-Submission_Abbreviation|BIP 23 Submission Abbreviation "submit/coinbase"]]
  39 | +* [[#user-content-Mutations|BIP 23 Mutation "time/increment"]] (only required for servers)

murchandamus commented at 11:35 PM on January 26, 2026:

* [[bip-0022.mediawiki#optional-long-polling|BIP 22 Long Polling]]
* [[#basic-pool-extensions|BIP 23 Basic Pool Extensions]]
* [[#mutations|BIP 23 Mutation "coinbase/append"]]
* [[#submission-abbreviation|BIP 23 Submission Abbreviation "submit/coinbase"]]
* [[#mutations|BIP 23 Mutation "time/increment"]] (only required for servers)

in bip-0023.mediawiki:38 in f87a5a31ec

  40 |  
  41 |  It can be said to have BIP 23 Level 2 support if it also implements:
  42 | -* [[#Mutations|BIP 23 Mutation "transactions/add"]]
  43 | -* [[#Block Proposals|BIP 23 Block Proposals]]
  44 | +* [[#user-content-Mutations|BIP 23 Mutation "transactions/add"]]
  45 | +* [[#user-content-Block_Proposals|BIP 23 Block Proposals]]

murchandamus commented at 11:36 PM on January 26, 2026:

* [[#mutations|BIP 23 Mutation "transactions/add"]]
* [[#block-proposals|BIP 23 Block Proposals]]

in bip-0023.mediawiki:90 in f87a5a31ec

  86 | @@ -87,7 +87,7 @@ This is accomplished by calling getblocktemplate with two keys:
  87 |  The block data MUST be validated and checked against the server's usual acceptance rules (excluding the check for a valid proof-of-work).
  88 |  If it is found to be in violation of any of these rules, the server MUST return one of the following:
  89 |  * Null if it is acceptable as-is, with the same workid (if any) as provided. Note that this SHOULD NOT invalidate the old template's claim to the same workid.
  90 | -* A String giving the reason for the rejection (see [[bip-0022.mediawiki#appendix-example-rejection-reasons|example rejection reasons]]).
  91 | +* A String giving the reason for the rejection (see [[bip-0022.mediawiki#user-content-appendix-example-rejection-reasons|example rejection reasons]]).

murchandamus commented at 11:37 PM on January 26, 2026:

The original works here for me.

* A String giving the reason for the rejection (see [[bip-0022.mediawiki#appendix-example-rejection-reasons|example rejection reasons]]).

in bip-0342.mediawiki:51 in f87a5a31ec

  46 | @@ -47,8 +47,8 @@ Additionally, the new tapscript <code>OP_SUCCESS</code> opcodes allow introducin
  47 |  
  48 |  The rules below only apply when validating a transaction input for which all of the conditions below are true:
  49 |  * The transaction input is a '''segregated witness spend''' (i.e., the scriptPubKey contains a witness program as defined in [[bip-0141.mediawiki|BIP141]]).
  50 | -* It is a '''taproot spend''' as defined in [[bip-0341.mediawiki#design|BIP341]] (i.e., the witness version is 1, the witness program is 32 bytes, and it is not P2SH wrapped).
  51 | -* It is a '''script path spend''' as defined in [[bip-0341.mediawiki#design|BIP341]] (i.e., after removing the optional annex from the witness stack, two or more stack elements remain).
  52 | +* It is a '''taproot spend''' as defined in [[bip-0341.mediawiki#user-content-design|BIP341]] (i.e., the witness version is 1, the witness program is 32 bytes, and it is not P2SH wrapped).
  53 | +* It is a '''script path spend''' as defined in [[bip-0341.mediawiki#user-content-design|BIP341]] (i.e., after removing the optional annex from the witness stack, two or more stack elements remain).

murchandamus commented at 11:38 PM on January 26, 2026:

These two already worked for me in the original.

murchandamus commented at 11:41 PM on January 26, 2026: member

On a second look, I agree that some of the existing links were broken, but I propose a different approach to sanitizing them.

murchandamus added the label PR Author action required on Jan 26, 2026

murchandamus commented at 10:27 PM on February 27, 2026: member

Since this had been dormant for a bit, I took the liberty to apply the proposed changes and to address the remaining anchors that used the broken format or relied on user-content-.

murchandamus removed the label PR Author action required on Feb 27, 2026

murchandamus force-pushed on Feb 27, 2026

Fix broken anchor links 835e7107b8

BIP22: fix anchor links 42303cbdf8

BIP23: Fix anchor links 5137d59442

BIP342: Fix anchor links 32b7adf847

Fix other broken anchors

Used the following `sed` command and manually verified the unstaged
changes. Special cases that were not committed included external links
to Wikipedia which are case-sensitive, links specific lines in code, a
link to a title with a slash that had to be cleaned up, and links to
citations on the BIP repository that contain an underscore.

```
sed -E -i '
s/(\[\[[^][]*#)([^]|]*)(\||\]\])/\1\L\2\E\3/g
:again
s/(\[\[[^][]*#)([^]|]*)([: _]+)([^]|]*)(\||\]\])/\1\2-\4\5/g
t again
' bip-0*mediawiki
```

b3a069464a

Eliminate remaining "user-content" anchor links 442e9628b3

murchandamus force-pushed on Apr 28, 2026

murchandamus commented at 12:31 AM on April 28, 2026: member

Fixed the merge conflict with a recent change to BIP375.

murchandamus removed the label Bug fix on Apr 28, 2026

murchandamus added the label Link fix on Apr 28, 2026

jonatack approved

jonatack commented at 8:42 PM on May 5, 2026: member

ACK

jonatack renamed this:
~~Fix broken anchor links in BIP 0342, BIP 0022, BIP 0023~~
Fix broken anchor links
on May 5, 2026

jonatack merged this on May 5, 2026

jonatack closed this on May 5, 2026

jonatack removed the label Proposed BIP modification on May 5, 2026