Fix/missing openbolt topic links and subtopic summaries #387
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| {%- comment -%} | ||
| child_topics.html — auto-generates an overview page's "on this page" list of | ||
| sub-topics from the site nav list, so parent-with-link sections don't need a | ||
| hand-maintained list of their sub-topics in the page body. | ||
|
|
||
| Renders a `<ul>` of child topic links for an overview page whose nav entry | ||
| has both `link:` and `items:` (e.g., OpenBolt's "Plans"). | ||
|
|
||
| For each child: title as a link + first paragraph of the child's rendered | ||
| content as a short description. Children that don't resolve to a doc in the | ||
| current collection (e.g., missing rake-generated reference pages) render as | ||
| a bare link with no description. | ||
|
|
||
| Data source: the entry for this page in `_data/nav/<page.nav>.yml`. The | ||
| matching `nav_base` (URL prefix) is looked up in `_data/nav_map.yml`. | ||
| {%- endcomment -%} | ||
|
|
||
| {%- assign nav_base = nil -%} | ||
| {%- for entry in site.data.nav_map -%} | ||
| {%- if entry.nav_key == page.nav -%} | ||
| {%- assign nav_base = entry.base -%} | ||
| {%- break -%} | ||
| {%- endif -%} | ||
| {%- endfor -%} | ||
|
|
||
| {%- assign page_subpath = page.url | remove_first: nav_base -%} | ||
|
|
||
| {%- comment -%} | ||
| Find the nav entry for the current page. Only matches entries with `items:`, | ||
| so pages whose nav entry has `link:` but no children (leaf pages) render | ||
| nothing here. | ||
| {%- endcomment -%} | ||
| {%- assign current_section = nil -%} | ||
| {%- for item in site.data.nav[page.nav] -%} | ||
| {%- if item.link == page_subpath and item.items -%} | ||
| {%- assign current_section = item -%} | ||
| {%- break -%} | ||
| {%- endif -%} | ||
| {%- endfor -%} | ||
|
|
||
| {%- if current_section -%} | ||
| <ul> | ||
| {%- for child in current_section.items -%} | ||
| {%- assign child_link_first_char = child.link | slice: 0 -%} | ||
| {%- if child_link_first_char == '/' -%} | ||
| {%- assign child_url = child.link -%} | ||
| {%- else -%} | ||
| {%- assign child_url = child.link | prepend: nav_base -%} | ||
| {%- endif -%} | ||
|
|
||
| {%- assign child_doc = nil -%} | ||
| {%- for doc in site[page.collection] -%} | ||
| {%- if doc.url == child_url -%} | ||
| {%- assign child_doc = doc -%} | ||
| {%- break -%} | ||
| {%- endif -%} | ||
| {%- endfor -%} | ||
|
|
||
| {%- comment -%} | ||
| Extract the child's first intro paragraph for the description. | ||
|
Contributor
There was a problem hiding this comment. I think I'd rather that we populate the front matter description field. Fwiw, the example you linked doesn't autogenerate descriptions. See "running plans" on https://help.puppet.com/bolt/current/topics/plans.htm |
||
|
|
||
| Every child page begins with `# Heading` then a plain intro paragraph, | ||
| so splitting the rendered HTML on `<p>` skips the `<h1>` and lands on the | ||
| first real paragraph. | ||
|
|
||
| `child_doc.content` is piped through `markdownify` first because Jekyll | ||
| only guarantees it holds rendered HTML for docs that happen to be built | ||
| before this page; docs built afterward still hold raw Markdown. Running | ||
| `markdownify` normalizes both cases to HTML so the `<p>` split is | ||
| deterministic regardless of build order. | ||
| {%- endcomment -%} | ||
| {%- assign first_para = nil -%} | ||
| {%- if child_doc -%} | ||
| {%- assign child_html = child_doc.content | markdownify -%} | ||
| {%- assign after_first_p = child_html | split: '<p>' -%} | ||
| {%- if after_first_p.size > 1 -%} | ||
| {%- assign first_para = after_first_p[1] | split: '</p>' | first -%} | ||
| {%- endif -%} | ||
| {%- endif -%} | ||
|
|
||
| {%- comment -%} | ||
| Title and description share one `<p>` (separated by a `<br>`) so the theme's | ||
| `.vp-doc p { margin: 16px 0 }` doesn't stack two paragraph margins between | ||
| them, which would push the description well below the link. | ||
| {%- endcomment -%} | ||
| <li> | ||
| <p><a href="{{ child_url }}">{{ child.text }}</a>{% if first_para %}<br> | ||
| {{ first_para }}{% endif %}</p> | ||
| </li> | ||
| {%- endfor -%} | ||
| </ul> | ||
| {%- endif -%} | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The child-topics list only renders under
/openbolt/latest/. Each collection also publishes at its versioned prefix (/openbolt/5.x/, via the_openbolt_latestsymlink), but nav_map has a singlebase: /openbolt/latest/for this nav key, so on a 5.x pageremove_first: nav_basestrips nothing, no nav entry matches, and the include silently emits nothing. Deriving the base from the page's own URL (same technique assidebar.html) works under both prefixes, and won't need nav_map bookkeeping when 6.x lands:Tested locally: with this,
/openbolt/5.x/plans.htmlrenders the full list with version-correct child links (descriptions too, since thesite[page.collection]lookup then matches), and/openbolt/latest/renders exactly as before.