# Documenter.jl and markdown headings in docstrings
**URL:** https://discourse.julialang.org/t/documenter-jl-and-markdown-headings-in-docstrings/135094
**Category:** New to Julia
**Tags:** question, documenter
**Created:** [January 16, 2026, 1:08pm UTC](https://discourse.julialang.org/t/documenter-jl-and-markdown-headings-in-docstrings/135094 "2026-01-16T13:08:52Z")
**Posts on this page:** 3
**Page:** 1
### Author:  [@alametti](https://discourse.julialang.org/u/alametti)
#### Post date: [January 16, 2026, 1:08pm UTC](https://discourse.julialang.org/t/documenter-jl-and-markdown-headings-in-docstrings/135094/1 "2026-01-16T13:08:52Z")
Apologies as I am new to Julia and still trying to wrap my head around Julia’s documentation style (avoiding argument lists and expected output, etc).
The Julia documentation recommends the use of markdown headings in function docstrings ([Documentation · The Julia Language](http://docs.julialang.org/en/v1/manual/documentation/#Writing-Documentation)), but a decision was made in 2023 to remove the semantic meaning of headings and simply parse the heading text to ``:
>
>
> Consider docstring:
>
> \`\`\`
> """
> foo(x, f, k)
>
> Do stuff
>
> \# Arguments
> \- …\`x\`: some argument
> \- \`f\`: some function
> ## Pattern
> - \`f(t)\`
> - \`f(t, u)\`
> - \`f(t, u, c)\`
> \- \`k\`: some other argument
> """
> function foo(x, f, k)
> end
> \`\`\`
>
>
> In REPL help, the format is as expected: \\"Pattern\\" is indented and a lower level heading as \\"Arguments\\"
>
> When making the documentation with Documenter on the other hand, \\"Pattern\\" gets translated to \\\ while \\"Arguements\\" only becomes \\\, not \\\. Therefore it looks quite off.
>
> Using \\\ for \\"Arguments\\" is obviously not a good solution either
> =\> Idea: translate all heading levels in docstrings to \\\ instead of \\\
>
>
> fixes #2308
> added search through markdown-lists in docstrings to find headings …for rewrite from heading to strong
While this causes no issues in the vast majority of cases, it does mean that:
1. Nested headings such as
```markdown
# Usage
## Arguments
```
are flattened into
```html
Usage
Arguments
```
without preserving the hierarchy or any way to differentiate between the two, even with custom stylesheets, etc.
2. It seems packages that render documentation into a “printable” format based on Documenter.jl’s AST cannot handle headings in docstrings properly (since they are removed and replaced by `strong`), which can, for example, lead to the insertion of inappropriate page breaks after headings since they no longer have any special semantic meaning.
Given this design choice, should I be writing docstrings without headings? In the event that a function or module requires more complex documentation, is it the “Julian” way that such documentation must then not be in close proximity to the code but potentially several directories away?
---
### Author:  [@cormullion](https://discourse.julialang.org/u/cormullion)
#### Post date: [January 16, 2026, 2:44pm UTC](https://discourse.julialang.org/t/documenter-jl-and-markdown-headings-in-docstrings/135094/2 "2026-01-16T14:44:44Z")
This issue is open:
>
>
> For example, in the source docs \[here\](https://github.com/JuliaDocs/DocStringExt…ensions.jl/blob/master/src/DocStringExtensions.jl) there are some headings like \`# Introduction\`, \`# Examples\`, etc.; but in the \[rendered page\](https://juliadocs.github.io/DocStringExtensions.jl/latest/) these show up as mere \`\\`-ly formatted text.
>
> Ideally the headings in docstrings should be preserved (converted into lower-level headings if needed to fit within the surrounding content). But in case that's not possible, it would be nice to at least add HTML anchors (\`id=\` or \`name=\` attributes) to the elements corresponding to headings in the source docs, so that they can be directly linked to.
---
### Author:  [@alametti](https://discourse.julialang.org/u/alametti)
#### Post date: [January 16, 2026, 5:04pm UTC](https://discourse.julialang.org/t/documenter-jl-and-markdown-headings-in-docstrings/135094/3 "2026-01-16T17:04:23Z")
I saw that, but it is this issue that was ultimately chosen as the solution:
>
>
> Consider docstring:
>
> \`\`\`
> """
> foo(x, f, k)
>
> Do stuff
>
> \# Arguments
> \- …\`x\`: some argument
> \- \`f\`: some function
> ## Pattern
> - \`f(t)\`
> - \`f(t, u)\`
> - \`f(t, u, c)\`
> \- \`k\`: some other argument
> """
> function foo(x, f, k)
> end
> \`\`\`
>
>
> In REPL help, the format is as expected: \\"Pattern\\" is indented and a lower level heading as \\"Arguments\\"
>
> When making the documentation with Documenter on the other hand, \\"Pattern\\" gets translated to \\\ while \\"Arguements\\" only becomes \\\, not \\\. Therefore it looks quite off.
>
> Using \\\ for \\"Arguments\\" is obviously not a good solution either
> =\> Idea: translate all heading levels in docstrings to \\\ instead of \\\
The issue you are linking hasn’t had any activity since 2023, so I assume that the decision is somewhat permanent.