Skip to content

Fix #729: Improve TOC rendering for items with header attribute #774

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jacebrowning merged 1 commit into from
Jun 8, 2026
Merged

Fix #729: Improve TOC rendering for items with header attribute #774

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions doorstop/core/publishers/html.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,12 +355,20 @@ def table_of_contents(self, linkify=None, obj=None):
for item in iter_items(toc_doc):
# Check if item has the attribute heading.
if item.heading:
lines = item.text.splitlines()
heading = lines[0] if lines else ""
if item.header:
heading = "{h}".format(h=item.header)
else:
lines = item.text.splitlines()
heading = lines[0] if lines else ""
# This is for non-heading items.
elif item.header:
heading = "{h}".format(h=item.header)
else:
heading = item.uid
lines = item.text.splitlines()
heading = lines[0] if lines else ""
# For normative items, the UID is of interest, so append it.
if item.normative:
heading = heading + " (" + str(item.uid) + ")"
if settings.PUBLISH_HEADING_LEVELS:
level = format_level(item.level)
lbl = "{lev} {h}".format(lev=level, h=heading)
Expand Down
20 changes: 14 additions & 6 deletions doorstop/core/publishers/markdown.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,13 +168,19 @@ def table_of_contents(self, linkify=None, obj=None):

# Check if item has the attribute heading.
if item.heading:
lines = item.text.splitlines()
heading = lines[0] if lines else ""
if item.header:
heading = "{h}".format(h=item.header)
else:
lines = item.text.splitlines()
heading = lines[0] if lines else ""
elif item.header:
heading = "{h}".format(h=item.header)
else:
heading = item.uid

lines = item.text.splitlines()
heading = lines[0] if lines else ""
# For normative items, the UID is of interest, so append it.
if item.normative:
heading = heading + " (" + str(item.uid) + ")"
if settings.PUBLISH_HEADING_LEVELS:
level = format_level(item.level)
lbl = "{lev} {h}".format(lev=level, h=heading)
Expand Down Expand Up @@ -233,9 +239,11 @@ def _generate_heading_from_item(self, item, to_html=False):
if settings.ENABLE_HEADERS:
if item.header:
if to_html:
uid = "{h} <small>{u}</small>".format(h=item.header, u=item.uid)
uid = "{h} <small>({u})</small>".format(
h=item.header, u=item.uid
)
else:
uid = "{h} _{u}_".format(h=item.header, u=item.uid)
uid = "{h} _({u})_".format(h=item.header, u=item.uid)
else:
uid = "{u}".format(u=item.uid)

Expand Down
56 changes: 38 additions & 18 deletions doorstop/core/publishers/tests/test_publisher_html.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -315,12 +315,16 @@ def test_toc_no_links_or_heading_levels(self):
"""Verify the table of contents is generated with heading levels"""
expected = [
{"depth": 0, "text": "Table of Contents", "uid": "toc"},
{"depth": 3, "text": "1.2.3 REQ001", "uid": ""},
{"depth": 2, "text": "1.4 REQ003", "uid": ""},
{"depth": 2, "text": "1.5 REQ006", "uid": ""},
{"depth": 2, "text": "1.6 REQ004", "uid": ""},
{"depth": 2, "text": "2.1 Plantuml", "uid": ""},
{"depth": 2, "text": "2.1 REQ2-001", "uid": ""},
{
"depth": 3,
"text": "1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)",
"uid": "",
},
{"depth": 2, "text": "1.4 Unicode: -40° ±1% (REQ003)", "uid": ""},
{"depth": 2, "text": "1.5 Hello, world! (REQ006)", "uid": ""},
{"depth": 2, "text": "1.6 Hello, world! (REQ004)", "uid": ""},
{"depth": 2, "text": "2.1 Plantuml (REQ002)", "uid": ""},
{"depth": 2, "text": "2.1 Hello, world! (REQ2-001)", "uid": ""},
]
html_publisher = publisher.check(".html", self.document)
toc = html_publisher.table_of_contents(linkify=None, obj=self.document)
Expand All @@ -331,12 +335,16 @@ def test_toc_no_links(self):
"""Verify the table of contents is generated without heading levels"""
expected = [
{"depth": 0, "text": "Table of Contents", "uid": "toc"},
{"depth": 3, "text": UID("REQ001"), "uid": ""},
{"depth": 2, "text": UID("REQ003"), "uid": ""},
{"depth": 2, "text": UID("REQ006"), "uid": ""},
{"depth": 2, "text": UID("REQ004"), "uid": ""},
{"depth": 2, "text": "Plantuml", "uid": ""},
{"depth": 2, "text": UID("REQ2-001"), "uid": ""},
{
"depth": 3,
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)",
"uid": "",
},
{"depth": 2, "text": "Unicode: -40° ±1% (REQ003)", "uid": ""},
{"depth": 2, "text": "Hello, world! (REQ006)", "uid": ""},
{"depth": 2, "text": "Hello, world! (REQ004)", "uid": ""},
{"depth": 2, "text": "Plantuml (REQ002)", "uid": ""},
{"depth": 2, "text": "Hello, world! (REQ2-001)", "uid": ""},
]

html_publisher = publisher.check(".html", self.document)
Expand All @@ -347,12 +355,24 @@ def test_toc(self):
"""Verify the table of contents is generated with an ID for the heading"""
expected = [
{"depth": 0, "text": "Table of Contents", "uid": "toc"},
{"depth": 3, "text": "1.2.3 REQ001", "uid": UID("REQ001")},
{"depth": 2, "text": "1.4 REQ003", "uid": UID("REQ003")},
{"depth": 2, "text": "1.5 REQ006", "uid": UID("REQ006")},
{"depth": 2, "text": "1.6 REQ004", "uid": UID("REQ004")},
{"depth": 2, "text": "2.1 Plantuml", "uid": UID("REQ002")},
{"depth": 2, "text": "2.1 REQ2-001", "uid": UID("REQ2-001")},
{
"depth": 3,
"text": "1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)",
"uid": UID("REQ001"),
},
{
"depth": 2,
"text": "1.4 Unicode: -40° ±1% (REQ003)",
"uid": UID("REQ003"),
},
{"depth": 2, "text": "1.5 Hello, world! (REQ006)", "uid": UID("REQ006")},
{"depth": 2, "text": "1.6 Hello, world! (REQ004)", "uid": UID("REQ004")},
{"depth": 2, "text": "2.1 Plantuml (REQ002)", "uid": UID("REQ002")},
{
"depth": 2,
"text": "2.1 Hello, world! (REQ2-001)",
"uid": UID("REQ2-001"),
},
]
html_publisher = publisher.check(".html", self.document)
toc = html_publisher.table_of_contents(linkify=True, obj=self.document)
Expand Down
37 changes: 19 additions & 18 deletions doorstop/core/publishers/tests/test_publisher_markdown.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,12 +225,12 @@ def test_toc_no_links_or_heading_levels(self):
"""Verify the table of contents is generated with heading levels"""
expected = """### Table of Contents

* 1.2.3 REQ001
* 1.4 REQ003
* 1.5 REQ006
* 1.6 REQ004
* 2.1 Plantuml
* 2.1 REQ2-001\n"""
* 1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)
* 1.4 Unicode: -40° ±1% (REQ003)
* 1.5 Hello, world! (REQ006)
* 1.6 Hello, world! (REQ004)
* 2.1 Plantuml (REQ002)
* 2.1 Hello, world! (REQ2-001)\n"""
md_publisher = publisher.check(".md", self.document)
toc = md_publisher.table_of_contents(linkify=None, obj=self.document)
self.assertEqual(expected, toc)
Expand All @@ -240,12 +240,13 @@ def test_toc_no_links(self):
"""Verify the table of contents is generated without heading levels"""
expected = """### Table of Contents

* REQ001
* REQ003
* REQ006
* REQ004
* Plantuml
* REQ2-001\n"""
* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)
* Unicode: -40° ±1% (REQ003)
* Hello, world! (REQ006)
* Hello, world! (REQ004)
* Plantuml (REQ002)
* Hello, world! (REQ2-001)
"""
md_publisher = publisher.check(".md", self.document)
toc = md_publisher.table_of_contents(linkify=None, obj=self.document)
self.assertEqual(expected, toc)
Expand All @@ -254,12 +255,12 @@ def test_toc(self):
"""Verify the table of contents is generated with an ID for the heading"""
expected = """### Table of Contents

* [1.2.3 REQ001](#123-req001-req001)
* [1.4 REQ003](#14-req003-req003)
* [1.5 REQ006](#15-req006-req006)
* [1.6 REQ004](#16-req004-req004)
* [2.1 Plantuml](#21-plantuml-req002-req002)
* [2.1 REQ2-001](#21-req2-001-req2-001)\n"""
* [1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)](#123-req001-req001)
* [1.4 Unicode: -40° ±1% (REQ003)](#14-req003-req003)
* [1.5 Hello, world! (REQ006)](#15-req006-req006)
* [1.6 Hello, world! (REQ004)](#16-req004-req004)
* [2.1 Plantuml (REQ002)](#21-plantuml-req002-req002)
* [2.1 Hello, world! (REQ2-001)](#21-req2-001-req2-001)\n"""
self.maxDiff = None
md_publisher = publisher.check(".md", self.document)
toc = md_publisher.table_of_contents(linkify=True, obj=self.document)
Expand Down
3 changes: 2 additions & 1 deletion doorstop/core/template.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,8 @@ def get_template(obj, path, ext, template):
log.info(
"Copying %s to %s",
each.template,
os.path.join(os.path.dirname(path), "template"),
template,
# os.path.join(os.path.dirname(path), "template"),
)
common.copy_dir_contents(each.template, template_dir)
else:
Expand Down
60 changes: 51 additions & 9 deletions doorstop/core/tests/files/published.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,18 +36,60 @@
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Contents
</a>
<ul class="dropdown-menu dropdown-menu-scrollable">
<li><a class="dropdown-item" href="#toc">Table of Contents</a></li>
<ul class="dropdown-menu" style="max-height: 70vh; overflow-y: auto;">
<li>
<a class="dropdown-item text-truncate"
href="#toc"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="toc">Table of Contents</a>
</li>
<ul>
<ul>
<ul>
<li><a class="dropdown-item" href="#REQ001">1.2.3 REQ001</a></li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ001"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ001">1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)</a>
</li>
</ul>
<li><a class="dropdown-item" href="#REQ003">1.4 REQ003</a></li>
<li><a class="dropdown-item" href="#REQ006">1.5 REQ006</a></li>
<li><a class="dropdown-item" href="#REQ004">1.6 REQ004</a></li>
<li><a class="dropdown-item" href="#REQ002">2.1 Plantuml</a></li>
<li><a class="dropdown-item" href="#REQ2-001">2.1 REQ2-001</a></li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ003"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ003">1.4 Unicode: -40° ±1% (REQ003)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ006"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ006">1.5 Hello, world! (REQ006)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ004"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ004">1.6 Hello, world! (REQ004)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ002"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ002">2.1 Plantuml (REQ002)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ2-001"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ2-001">2.1 Hello, world! (REQ2-001)</a>
</li>
</ul>
</ul>
</ul>
Expand Down Expand Up @@ -117,7 +159,7 @@ <h2 id="REQ006">1.5 REQ006</h2>
<p><em>Parent links:</em> <a href="REQ.html#REQ001">REQ001</a></p>
<h2 id="REQ004">1.6 REQ004</h2>
<p>Hello, world!</p>
<h2 id="REQ002">2.1 Plantuml <small>REQ002</small></h2>
<h2 id="REQ002">2.1 Plantuml <small>(REQ002)</small></h2>
<p>Hello, world!</p>
<p><code>plantuml format="svg_inline" alt="Use Cases of Doorstop" title="Use Cases of Doorstop"
@startuml
Expand Down
2 changes: 1 addition & 1 deletion doorstop/core/tests/files/published.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Hello, world!

Hello, world!

## 2.1 Plantuml _REQ002_ {#REQ002}
## 2.1 Plantuml _(REQ002)_ {#REQ002}

Hello, world!

Expand Down
60 changes: 51 additions & 9 deletions doorstop/core/tests/files/published2.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,18 +36,60 @@
<a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-expanded="false">
Contents
</a>
<ul class="dropdown-menu dropdown-menu-scrollable">
<li><a class="dropdown-item" href="#toc">Table of Contents</a></li>
<ul class="dropdown-menu" style="max-height: 70vh; overflow-y: auto;">
<li>
<a class="dropdown-item text-truncate"
href="#toc"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="toc">Table of Contents</a>
</li>
<ul>
<ul>
<ul>
<li><a class="dropdown-item" href="#REQ001">1.2.3 REQ001</a></li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ001"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ001">1.2.3 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod (REQ001)</a>
</li>
</ul>
<li><a class="dropdown-item" href="#REQ003">1.4 REQ003</a></li>
<li><a class="dropdown-item" href="#REQ006">1.5 REQ006</a></li>
<li><a class="dropdown-item" href="#REQ004">1.6 REQ004</a></li>
<li><a class="dropdown-item" href="#REQ002">2.1 Plantuml</a></li>
<li><a class="dropdown-item" href="#REQ2-001">2.1 REQ2-001</a></li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ003"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ003">1.4 Unicode: -40° ±1% (REQ003)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ006"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ006">1.5 Hello, world! (REQ006)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ004"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ004">1.6 Hello, world! (REQ004)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ002"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ002">2.1 Plantuml (REQ002)</a>
</li>
<li>
<a class="dropdown-item text-truncate"
href="#REQ2-001"
data-bs-toggle="tooltip"
data-bs-placement="left"
title="REQ2-001">2.1 Hello, world! (REQ2-001)</a>
</li>
</ul>
</ul>
</ul>
Expand Down Expand Up @@ -117,7 +159,7 @@ <h2 id="REQ006">1.5 REQ006</h2>
<p><em>Links: REQ001</em></p>
<h2 id="REQ004">1.6 REQ004</h2>
<p>Hello, world!</p>
<h2 id="REQ002">2.1 Plantuml <small>REQ002</small></h2>
<h2 id="REQ002">2.1 Plantuml <small>(REQ002)</small></h2>
<p>Hello, world!</p>
<p><code>plantuml format="svg_inline" alt="Use Cases of Doorstop" title="Use Cases of Doorstop"
@startuml
Expand Down
2 changes: 1 addition & 1 deletion doorstop/core/tests/files/published2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Hello, world!

Hello, world!

## 2.1 Plantuml _REQ002_ {#REQ002}
## 2.1 Plantuml _(REQ002)_ {#REQ002}

Hello, world!

Expand Down
Loading
Loading