# I don't get how header anchors work
**URL:** https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801
**Category:** v1: Troubleshooting (legacy)
**Created:** [February 14, 2025, 2:12pm UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801 "2025-02-14T14:12:08Z")
**Posts on this page:** 9
**Page:** 1
### Author:  [@snake\_case](https://community.silverbullet.md/u/snake_case)
#### Post date: [February 14, 2025, 2:12pm UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/1 "2025-02-14T14:12:08Z")
So, I have a page for the clipouts from books I read. The page is structured (rather poorly, I admit) like this:
```markdown
# Book Name Goes Here
- #some-kind-of-hashtag
- ## Excerpts
- ### Thematic header
- Lorem impsum
- Dolor sit amet
```
The thing is: I can’t seem to be able to embed the heading with its content from another page using transclusions syntax. OK, so here’s my clipout (heavily redacted, cause copyrighted material):
```markdown
- ### Make your own test
- 1. Create a new pipeline job in the **test** stage ...
2. Use the **images** keyword...
3. In the **script**...
4. Add **allow\_failure: true** to your job...
5. The second part...
```
In theory, it should be embeddable with a quick `![[clipouts#Make your own test]]`, and, indeed, editor suggests that, but the transclusion comes up empty and I couldn’t make it work.
The more fundamental question is: how embedding with headers even works? The documentation says this
> - `![[page name#header]]` embed only a section (guarded by the given header)
but that doesn’t really clear up ambiguity in any way. Where precisely the header starts and where does it end? Does it continue till we hit another header of any level? Only the same level? What about text, does it have to be indented to fall into the header? How all of this jives with outlines?
---
### Author:  [@caesiumtea](https://community.silverbullet.md/u/caesiumtea)
#### Post date: [February 14, 2025, 9:27pm UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/2 "2025-02-14T21:27:33Z")
Hmmm, on my end it seems like they work fine when there are no spaces in the heading name, but perhaps fail when there are spaces in it? In which case it might be a bug. Is that also true for you? Can you test and see if it works when you try to embed a single-word heading?
---
### Author:  [@snake\_case](https://community.silverbullet.md/u/snake_case)
#### Post date: [February 15, 2025, 7:40am UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/3 "2025-02-15T07:40:09Z")
Nope, tried replacing spaces with underscores, didn’t work. Tried reducing the header to a single word — did not work either. Also, [Transclusions page](https://silverbullet.md/Transclusions) of documentation uses a bunch of transclusions with spaces in their headers, so it works for them.
The funny thing is — pressing “link” icon in transclusions box reliably sends me to that header, but the transclusion box itself is empty.
---
### Author:  [@zef](https://community.silverbullet.md/u/zef)
#### Post date: [February 15, 2025, 10:59am UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/4 "2025-02-15T10:59:23Z")
First, I’m not sure if headers inside of bulleted lists are actually even a thing that markdown supports. I have never seen this before, so if it does anything that’s by accident. SilverBullet itself for sure has no support for it. Headers are supposed to be top-level only.
As to the question of transcluding a header, I had to look up the code that does this (which I didn’t write) and found it here: [silverbullet/common/query\_functions.ts at main · silverbulletmd/silverbullet · GitHub](https://github.com/silverbulletmd/silverbullet/blob/main/common/query_functions.ts#L122) A comment there say:
```javascript
// If the page link includes a header, select that header (up to the next header at the same level)
```
So assuming you’d use top level headers:
```markdown
# Header 1
## Header 1.1
Hello
# Header 2
# Header 3
```
Transcluding [[page#Header 1]] should result in:
```markdown
# Header 1
## Header 1.1
Hello
```
Playing with this, the implementation doesn’t seem perfect, but for this case it seems to work.
---
### Author:  [@snake\_case](https://community.silverbullet.md/u/snake_case)
#### Post date: [February 15, 2025, 11:51am UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/5 "2025-02-15T11:51:07Z")
First of all, thanks for chiming in and clarifying. I’m coming from Logseq and outlines with headers used to just work there, so I assumed it might work in SB as well. Outlines need headers and devising hacks to make text bold + increase its size + make this point in the outline linkable would be a huge pain point. Maybe I need to change my philosophy about this and just make a “core” document that embeds other chunks as transclusions, but even that is a hack in my opinion. I tried transcluding outlined headers and it works to some capacity: one would indeed get the section from the header to his next neighbor, but the markdown inside wouldn’t render. For example:
test/source
```markdown
- # Header 1
- lorem impsum dolor sit amet
- ## Header 1.1
- foo bar baz
- ### Header 1.1.1
- qwerty
```
test/target
Regarding my specific issue, I think I found why it breaks in my case.
test/source
```markdown
# Header 1
lorem impsum dolor sit amet
## Header 1.1
foo bar baz
# Header 2
abc def ghi
## Header 2.2
jkl mno pqr
```
test/target
```markdown
![[test/source#Header 1.1]]
![[test/source#Header 2.2]]
```
Header 1.1 embeds. Header 2.2 doesn’t. Why? I suspect because it’s the last non-top-level header of the document: there are no headers of the same level after it. If I go to test/source and remove one hash character from 2.2 to make it a top-level header — it embeds perfectly fine.
---
### Author:  [@caesiumtea](https://community.silverbullet.md/u/caesiumtea)
#### Post date: [February 16, 2025, 1:20am UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/6 "2025-02-16T01:20:29Z")
Just found that there’s already an open issue for this on GH, actually!
>
>
> section transclusion (e.g. \`!\[\[page name#title\]\]\`) does not render in case it's …the last section on the page and it's a h2 or higher (h3, h4, ...) heading.
I mmmmight try later to see if I can find the bug? Thanks Zef for pointing out the section of the code that applies to this feature!
PS, sorry for my bad info thinking it was related to spaces in the name haha, guess it was just a coincidence that on _my_ page the last header was the only one with a space in it. Thanks snake\_case for the correction!
---
### Author:  [@snake\_case](https://community.silverbullet.md/u/snake_case)
#### Post date: [February 16, 2025, 6:56am UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/7 "2025-02-16T06:56:47Z")
Huh, I should’ve checked github issues myself, so glad that it’s tracked already. Should I close the thread and mark your message as a solution? What’s the local policy on this?
---
### Author:  [@janssen-io](https://community.silverbullet.md/u/janssen-io)
#### Post date: [March 12, 2025, 4:10pm UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/8 "2025-03-12T16:10:04Z")
This was bugging me for quite some time and looking at the code I couldn’t see why it wouldn’t work. So I dug in and proposed a fix to @zef via a PR:
>
>
> The check if a match was found by the heading regex was incorrect. \`string.searc…h(regex)\` returns \`-1\` which is "truethy".
> Instead use a check if it's greater or equal than 0 (technically correct, but in practice it will even be bigger, because a next heading is at least a newline away).
>
> Fixes #1086
---
### Author:  [@zef](https://community.silverbullet.md/u/zef)
#### Post date: [March 12, 2025, 6:41pm UTC](https://community.silverbullet.md/t/i-dont-get-how-header-anchors-work/1801/9 "2025-03-12T18:41:16Z")
Merged!