Skip to content

Don't include subsections in site-wide table of contents #4065

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
merged 2 commits into from
Apr 2, 2025
Merged

Don't include subsections in site-wide table of contents #4065

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6d3441
Support shorthand Asciidoc IDs when building TOC
mudge Apr 1, 2025
989484a
Don't include subsections in the site-wide TOC
mudge Apr 1, 2025
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
176 changes: 44 additions & 132 deletions jekyll-assets/_layouts/docs.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,25 +25,14 @@ <h1 id="docs-header-title">
</div>
<div class="toc">
{% for subdir in site.data.nav %}
{% if subdir.toc[0] %}
<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="{{ subdir.path }}"
{% if page.url contains subdir.path %}
checked=true
{% endif %}
/>
<input class="toc-toggle-box" type="checkbox" id="{{ subdir.path }}" {% if page.url contains subdir.path %}checked{% endif %} />
<li>
<span>
<label class="toc-toggle" for="{{ subdir.path }}" onclick="event.stopPropagation()">
<div class="toc-toggle-container">
<a class="level1" href="{{ site.baseurl }}{{ subdir.path }}">
<a title="expand {{ item.title | markdownify }}"
{% if page.url contains subdir.path %}
class="bold toc-item"
{% else %}
class="toc-item"
{% endif %}
>
<a title="expand {{ item.title | markdownify }}" class="{% if page.url contains subdir.path %}bold {% endif %}toc-item">
{{ subdir.title | markdownify }}
</a>
</a>
Expand All @@ -52,126 +41,55 @@ <h1 id="docs-header-title">
</span>
</li>
{% for item in subdir.toc %}
<div class="itemcontents">
<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="{{ item.path }}"
{% if page.url contains item.path %}
checked=true
{% endif %}
/>
<li>
<span>
<label class="toc-toggle" for="{{ item.path }}">
<div class="toc-toggle-container">
<a class="level2" href="{{ site.baseurl }}{{ item.path }}">
<a title="expand {{ item.title | strip_html }}"
{% if page.url contains item.path %}
class="bold toc-item"
{% else %}
class="toc-item"
{% endif %}
>
{{ item.title | markdownify }}
</a>
</a>
</div>
</label>
</span>
</li>
{% if item.sections[0] %}
{% for entry in item.sections %}
<div class="itemcontents">
<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="{{ item.path }}#{{ entry.anchor }}"
{% if endcapture contains entry.anchor %}
checked=true
{% endif %}
/>
<li>
<span>
<label class="toc-toggle"
{% if entry.subsections[0] %}
for="{{ item.path }}#{{ entry.anchor }}"
{% else %}
{% endif %}>
<div class="toc-toggle-container">
{% if entry.subsections[0] %}
<a class="level3">
<a
id="{{ item.path }}#{{entry.anchor}}-toc"
href="{{ site.baseurl }}{{ item.path }}#{{ entry.anchor }}"
class="toc-item"
onclick="document.getElementById('mobile-toggle').checked = false; updateCurrentToc('{{ item.path }}#{{ entry.anchor }}-toc', '{{ item.path }}#{{ entry.anchor }}');"
title="expand {{ entry.heading | strip_html }}"
>
<script type="text/javascript">if (window.location.hash == '#{{ entry.anchor }}' && window.location.href.includes('{{ item.path }}')) initialiseCurrentToc('{{ item.path }}#{{entry.anchor}}-toc', '{{ item.path }}#{{ entry.anchor }}');
</script>
{{ entry.heading | markdownify }}
</a>
<div class="itemcontents">
<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="{{ item.path }}" {% if page.url contains item.path %}checked{% endif %} />
<li>
<span>
<label class="toc-toggle" for="{{ item.path }}">
<div class="toc-toggle-container">
<a class="level2" href="{{ site.baseurl }}{{ item.path }}">
<a title="expand {{ item.title | strip_html }}" class="{% if page.url contains item.path %}bold {% endif %}toc-item">
{{ item.title | markdownify }}
</a>
{% else %}
<a class="level3">
<a id="{{ item.path }}#{{entry.anchor}}-toc"
title="expand {{ entry.heading | strip_html }}"
href="{{ site.baseurl }}{{ item.path }}#{{ entry.anchor }}"
onclick="document.getElementById('mobile-toggle').checked = false; updateCurrentToc('{{ item.path }}#{{ entry.anchor }}-toc');"
class="toc-item no-dropdown"
>
<script type="text/javascript">if (window.location.hash == '#{{ entry.anchor }}' && window.location.href.includes('{{ item.path }}'))
initialiseCurrentToc('{{ item.path }}#{{entry.anchor}}-toc');
</script>
{{ entry.heading | markdownify }}
</a>
</div>
</label>
</span>
</li>
{% for entry in item.sections %}
<div class="itemcontents">
<ul class="sectlevel1">
<li>
<span>
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level3">
<a
href="{{ site.baseurl }}{{ item.path }}#{{ entry.anchor }}"
onclick="document.getElementById('mobile-toggle').checked = false"
class="toc-item no-dropdown"
>
{{ entry.heading | markdownify }}
</a>
</a>
</a>
{% endif %}
</div>
</label>
</span>
</li>
{% if entry.subsections[0] %}
{% for subentry in entry.subsections %}
<div class="itemcontents">
<ul class="sectlevel1">
<li>
<span>
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level4">
<a class="toc-item no-dropdown"
href="{{ site.baseurl }}{{ item.path }}#{{ subentry.anchor }}"
onclick="document.getElementById('mobile-toggle').checked = false; updateCurrentToc('{{ item.path }}#{{ entry.anchor }}-toc', '{{ item.path }}#{{ entry.anchor }}', '{{ item.path }}#{{ subentry.anchor }}-toc');"
id="{{ item.path }}#{{subentry.anchor}}-toc"
>
<script type="text/javascript">if (window.location.hash == '#{{ subentry.anchor }}' && window.location.href.includes('{{ item.path }}')) initialiseCurrentToc('{{ item.path }}#{{ entry.anchor }}-toc', '{{ item.path }}#{{ entry.anchor }}', '{{ item.path }}#{{ subentry.anchor }}-toc');
</script>
{{ subentry.heading | markdownify }}
</a>
</a>
</div>
</label>
</span>
</li>
</ul>
</div>
{% endfor %}
{% endif %}
</ul>
</div>
</div>
</label>
</span>
</li>
</ul>
</div>
{% endfor %}
{% endif %}
</ul>
</div>
{% endfor %}
</ul>
{% endif %}
{% endfor %}

{% endfor %}

<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="datasheets"
/>
<li>
<span>
<label class="toc-toggle" for="{{ subdir.path }}">
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level1">
<a title="PDF documentation" class="toc-item no-dropdown" href="https://datasheets.raspberrypi.com/" target="_blank">
Expand All @@ -185,11 +103,9 @@ <h1 id="docs-header-title">
</ul>

<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="pip"
/>
<li>
<span>
<label class="toc-toggle" for="{{ subdir.path }}">
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level1">
<a title="Raspberry Pi compliance documents" class="toc-item no-dropdown" href="https://pip.raspberrypi.com/" target="_blank">
Expand All @@ -203,11 +119,9 @@ <h1 id="docs-header-title">
</ul>

<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="tutorials"
/>
<li>
<span>
<label class="toc-toggle" for="{{ subdir.path }}">
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level1">
<a title="Hands-on hardware and software tutorials" class="toc-item no-dropdown" href="https://www.raspberrypi.com/tutorials/" target="_blank">
Expand All @@ -221,11 +135,9 @@ <h1 id="docs-header-title">
</ul>

<ul class="sectlevel1">
<input class="toc-toggle-box" type="checkbox" id="forums"
/>
<li>
<span>
<label class="toc-toggle" for="{{ subdir.path }}">
<label class="toc-toggle">
<div class="toc-toggle-container">
<a class="level1">
<a title="User and product support forums" class="toc-item no-dropdown" href="https://forums.raspberrypi.com" target="_blank">
Expand Down
62 changes: 0 additions & 62 deletions jekyll-assets/scripts/toc.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,65 +34,3 @@ function makeToc() {
handleTocOnResize();
}
}

var currentParentID;
var currentParentInputID;
var currentChildID;

function initialiseCurrentToc(parentID, parentInputID = null, childID = null) {
// highlight the new parent
var newParent = document.getElementById(parentID);
newParent.setAttribute('style', 'font-weight:bold');
currentParentID = parentID;

// if a parent input id is specified, expand the parent element
if (parentInputID) {
var newParentInput = document.getElementById(parentInputID);
newParentInput.click();
currentParentInputID = parentInputID;
}

// if a child is specified, highlight the child
if (childID) {
var newChild = document.getElementById(childID);
newChild.setAttribute('style', 'font-weight:bold');
currentChildID = childID;
}
}

function updateCurrentToc(parentID, parentInputID = null, childID = null) {
if (currentParentID == null && currentChildID == null) {
initialiseCurrentToc(parentID, parentInputID, childID)
} else {
// if a parent input id is specified, but no child, expand the parent element
// why no child? because if someone clicks the child within a parent, they don't want the parent section to collapse!
if (parentInputID && childID == null) {
var newParentInput = document.getElementById(parentInputID);
newParentInput.click();
currentParentInputID = parentInputID;
}

// if this is a new parent id, de-highlight the old parent and highlight the new one
if (currentParentID != parentID) {
var oldParent = document.getElementById(currentParentID);
oldParent.style.removeProperty('font-weight');
var newParent = document.getElementById(parentID);
newParent.setAttribute('style', 'font-weight:bold');
currentParentID = parentID;
}

// if there is an old child highlighted, un-highlight it
if (currentChildID) {
var oldChild = document.getElementById(currentChildID);
oldChild.style.removeProperty('font-weight');
}

// if there is a new child, highlight it
if (childID != null) {
var newChild = document.getElementById(childID);

newChild.setAttribute('style', 'font-weight:bold');
}
currentChildID = childID;
}
}
52 changes: 28 additions & 24 deletions scripts/create_nav.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,33 +122,37 @@ def read_file_with_includes(filepath, filelevel, mainfile, output_dir=None):
if m:
header_id = m.group(1)
else:
m = re.match(r'^\[(.*)\]\s*$', line)
m = re.match(r'^\[#(.+?)(?:,.*?)\]\s*$', line)
if m:
attrs = m.group(1).split(',')
last_line_was_discrete = 'discrete' in attrs
header_id = None
header_id = m.group(1)
else:
m = re.match(r'^(=+)\s+(.+?)\s*$', line)
m = re.match(r'^\[(.*)\]\s*$', line)
if m:
newlevel = len(m.group(1))
# Need to compute anchors for *every* header (updates file_headings)
heading = strip_adoc(m.group(2))
heading = re.sub(r"(\[\.contexttag )(\S+)(\]\*\S+\*)", "<strong class=\"contexttag \\2\">\\2</strong>", heading)
anchor = heading_to_anchor(top_level_file, heading, header_id)
if anchor in available_anchors[fullpath]:
raise Exception("Anchor {} appears twice in {}".format(anchor, fullpath))
available_anchors[fullpath].add(anchor)
if min_level <= newlevel <= max_level and not last_line_was_discrete:
entry = {'heading': heading, 'anchor': anchor}
if newlevel > level:
nav[-1]['sections'][-1]['subsections'] = []
level = newlevel
if level == 2:
nav[-1]['sections'].append(entry)
elif level == 3:
nav[-1]['sections'][-1]['subsections'].append(entry)
last_line_was_discrete = False
header_id = None
attrs = m.group(1).split(',')
last_line_was_discrete = 'discrete' in attrs
header_id = None
else:
m = re.match(r'^(=+)\s+(.+?)\s*$', line)
if m:
newlevel = len(m.group(1))
# Need to compute anchors for *every* header (updates file_headings)
heading = strip_adoc(m.group(2))
heading = re.sub(r"(\[\.contexttag )(\S+)(\]\*\S+\*)", "<strong class=\"contexttag \\2\">\\2</strong>", heading)
anchor = heading_to_anchor(top_level_file, heading, header_id)
if anchor in available_anchors[fullpath]:
raise Exception("Anchor {} appears twice in {}".format(anchor, fullpath))
available_anchors[fullpath].add(anchor)
if min_level <= newlevel <= max_level and not last_line_was_discrete:
entry = {'heading': heading, 'anchor': anchor}
if newlevel > level:
nav[-1]['sections'][-1]['subsections'] = []
level = newlevel
if level == 2:
nav[-1]['sections'].append(entry)
elif level == 3:
nav[-1]['sections'][-1]['subsections'].append(entry)
last_line_was_discrete = False
header_id = None
elif 'from_json' in tab:
tab_dir = os.path.join(adoc_dir, tab['directory'])
if os.path.exists(tab_dir):
Expand Down
Loading