docs: about usage

core/modules/parsers/wikiparser/rules/blockid.js

@@ -37,9 +37,9 @@ exports.parse = function() {
 		type: "blockid",
 		attributes: {
 			id: {type: "string", value: blockId || blockBeforeId},
-			// `true` means the block is before this node, in parent node's children list.
+			// `yes` means the block is before this node, in parent node's children list.
-			// `false` means the block is this node's parent node.
+			// empty means the block is this node's direct parent node.
-			previousSibling: {type: "boolean", value: Boolean(blockBeforeId)},
+			previousSibling: {type: "string", value: Boolean(blockBeforeId) ? "yes" : ""},
 		},
 		children: []
 	}];

core/modules/widgets/blockid.js

@@ -34,14 +34,14 @@ BlockIdWidget.prototype.render = function(parent,nextSibling) {
 };
 
 BlockIdWidget.prototype.hookFocusElementEvent = function(event) {
-	if(!event.param) return event;
+	if(!event || !event.param) return event;
 	var id = event.param.replace('#','');
 	if(id !== this.id) return event;
 	var selector = event.param || "",
 			element,
 			baseElement = event.event && event.event.target ? event.event.target.ownerDocument : document;
 	element = $tw.utils.querySelectorSafe(selector,baseElement);
-	if(!element.parentNode) return;
+	if(!element || !element.parentNode) return;
 	element = element.parentNode;
 	// need to check if the block is before this node
 	if(this.previousSibling && element.previousSibling) {
@@ -67,7 +67,7 @@ Compute the internal state of the widget
 BlockIdWidget.prototype.execute = function() {
 	// Get the id from the parse tree node or manually assigned attributes
 	this.id = this.getAttribute("id");
-	this.previousSibling = this.getAttribute("previousSibling");
+	this.previousSibling = this.getAttribute("previousSibling") === "yes";
 	// Make the child widgets
 	this.makeChildWidgets();
 };

editions/tw5.com/tiddlers/widgets/BlockIdWidget.tid

@@ -0,0 +1,39 @@
+caption: block id
+created: 20230916061829840
+modified: 20230916062346854
+tags: Widgets
+title: BlockIdWidget
+type: text/vnd.tiddlywiki
+
+! Introduction
+
+The block id widget make an anchor that can be focused and jump to.
+
+! Content and Attributes
+
+The content of the `<$blockid>` widget is ignored.
+
+|!Attribute |!Description |
+|id |The unique id for the block |
+|previousSibling |`yes` means the block is before this node, in parent node's children list, else it means the block is this node's direct parent node. |
+
+See [[Block Level Links in WikiText^block091606]] for WikiText syntax of block ID.
+
+! Example
+
+<<wikitext-example-without-html """The block id widget is invisible, and is usually located at the end of the line. <$blockid id="exampleid1"/>
+
+[[exampleid1|BlockIdWidget^exampleid1]]
+""">>
+
+<<wikitext-example-without-html """You can refer to the block that is a line before the block id widget. Make sure block id widget itself is in a block (paragraph).
+
+<p><$blockid id="exampleid2" previousSibling="yes"/></p>
+
+[[exampleid2|BlockIdWidget^exampleid2]]
+""">>
+
+<<wikitext-example-without-html """The block id widget is invisible, and is usually located at the end of the line. <$blockid id="exampleid1"/>
+
+[[exampleid1|BlockIdWidget^exampleid1]]
+""">>

editions/tw5.com/tiddlers/wikitext/Block Level Links in WikiText.tid

@@ -0,0 +1,44 @@
+caption: Block Level Links
+created: 20230916061138153
+modified: 20230916062623280
+tags: WikiText
+title: Block Level Links in WikiText
+type: text/vnd.tiddlywiki
+
+! Adding ID for block ^block091606
+
+The basic syntax for block id is:
+
+<<wikitext-example src:"There is a block id that is invisible, but you can find it using developer tool's inspect element feature. ^BlockLevelLinksID1">>
+
+# Don't forget the space between the end of the line and the `^`.
+# And there is no space between `^` and the id.
+# ID should be a [ext[valid HTML element ID|https://developer.mozilla.org/docs/Web/HTML/Global_attributes/id]], to avoid inadvertent errors, only ASCII letters, digits, '_', and '-' should be used, and the value for an id attribute should start with a letter.
+
+And this block id widget will be rendered as an invisible element:
+
+```html
+<span id="BlockLevelLinksID1" data-block-id="BlockLevelLinksID1" class="tc-block-id"></span>
+```
+
+!! Adding id to previous block
+
+Some block, for example, code block, can't be suffixed by `^id`, but we can add the id in the next line, with no space prefix to it.
+
+<<wikitext-example src:"```css
+.main {
+  display: none;
+}
+```
+
+^BlockLevelLinksID2
+
+">>
+
+! Link to the block ID
+
+Adding `^blockID` after the title in the link, will make this link highlight the block with that ID.
+
+<<wikitext-example-without-html src:"[[Link to BlockLevelLinksID1|Block Level Links in WikiText^BlockLevelLinksID1]]">>
+
+<<wikitext-example-without-html src:"[[Link to BlockLevelLinksID2|Block Level Links in WikiText^BlockLevelLinksID2]]">>

editions/tw5.com/tiddlers/wikitext/Linking in WikiText.tid

@@ -123,3 +123,9 @@ See also another example of [[constructing dynamic links|Concatenating text and
 In TiddlyWiki anchor links can help us link to target points and distinct sections within rendered tiddlers. They can help the reader navigate longer tiddler content.
 
 See [[Anchor Links using HTML]] for more information.
+
+! Linking within tiddlers - Link to block
+
+You can link to a specific block within a tiddler using `^blockId` syntax. You will also get block level backlinks with this technique. Some examples are in [[BlockIdWidget^exampleid1]].
+
+See [[Block Level Links in WikiText]] for more information.