Update docs templates#755
Conversation
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
✅ Deploy Preview for open-component-model ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughAdds a new concept documentation template, restructures how-to and tutorial templates to use semantic headings, details wrappers, and placeholder-driven content, and appends a single token to the repository wordlist. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Comment Tip CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required. |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@content_templates/template-how-to.md`:
- Line 155: The checklist intro uses incorrect preposition ("comply to"); update
the sentence in the template (the line containing "Make sure to comply to our
[CONTRIBUTING guide](../CONTRIBUTING.md)") to use "comply with" instead — e.g.
change it to "Make sure to comply with our [CONTRIBUTING
guide](../CONTRIBUTING.md)" (or rephrase to "Please follow our CONTRIBUTING
guide") to fix the grammar.
- Line 30: The relref link "See [Diagram Color Guide]({{< relref
"content_templates/template-tutorial.md#diagram-color-guide" >}})" points to a
non-existent anchor "#diagram-color-guide"; either update that relref target to
match the actual heading slug in the tutorial template (adjust the anchor to the
exact heading text/slug) or add the missing "Diagram Color Guide" heading to the
tutorial template; change the link in template-how-to.md (the "Diagram Color
Guide" relref) so it matches the real heading slug or create the heading in
template-tutorial.md so the anchor resolves.
In `@content_templates/template-tutorial.md`:
- Around line 84-85: Add a blank line before the "### Create the component
constructor file" heading (i.e., ensure a newline between the preceding {{< step
>}} shortcode and the H3) to satisfy markdown linting, and remove the unmatched
trailing "**" from the other heading text (the heading that currently ends with
a stray "**") so the markdown is balanced; update the heading string to plain
markdown text (e.g., remove or properly close bold markers) in
template-tutorial.md.
- Line 252: Replace the incorrect phrase "comply to" with "comply with" in the
publishing checklist intro; specifically update the line containing "Make sure
to comply to our [CONTRIBUTING guide](../CONTRIBUTING.md)" to read "Make sure to
comply with our [CONTRIBUTING guide](../CONTRIBUTING.md)".
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 9fb4133e-f0e7-4795-a306-23f8550a52b1
📒 Files selected for processing (3)
content_templates/template-concept.mdcontent_templates/template-how-to.mdcontent_templates/template-tutorial.md
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
.github/config/wordlist.txt (1)
470-470: Avoid adding overly generic short tokens to the global wordlist.
tosis broad/ambiguous and can hide genuine typos across the entire docs set. Prefer a scoped suppression in the specific document (or a more explicit canonical term/casing) instead of a global dictionary entry.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/config/wordlist.txt at line 470, Remove the overly generic global token "tos" from the shared wordlist and instead add a scoped suppression or explicit canonical term in the specific document where "tos" is valid; locate the entry "tos" in the global wordlist (the exact token shown in the diff) and delete it, then add a document-level exception (e.g., a per-file or per-directory suppression in that document's lint/config) or replace usages with a clearer canonical form to avoid hiding typos across the docs.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.github/config/wordlist.txt:
- Line 470: Remove the overly generic global token "tos" from the shared
wordlist and instead add a scoped suppression or explicit canonical term in the
specific document where "tos" is valid; locate the entry "tos" in the global
wordlist (the exact token shown in the diff) and delete it, then add a
document-level exception (e.g., a per-file or per-directory suppression in that
document's lint/config) or replace usages with a clearer canonical form to avoid
hiding typos across the docs.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5f4cefb3-297f-4aec-b944-c7d4dea251c0
📒 Files selected for processing (2)
.github/config/wordlist.txtcontent_templates/template-tutorial.md
🚧 Files skipped from review as they are similar to previous changes (1)
- content_templates/template-tutorial.md
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
There was a problem hiding this comment.
♻️ Duplicate comments (2)
content_templates/template-tutorial.md (1)
152-152:⚠️ Potential issue | 🟡 MinorFix malformed heading markdown.
The heading has an unmatched trailing
**, which can break rendering/linting. Change it to### Verify the result.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content_templates/template-tutorial.md` at line 152, Fix the malformed markdown heading by removing the unmatched trailing bold markers: locate the heading line currently written as "### Verify the result**" in content_templates/template-tutorial.md and change it to "### Verify the result" so the heading is well-formed and no linting/rendering errors occur.content_templates/template-how-to.md (1)
30-30:⚠️ Potential issue | 🟡 MinorBroken relref anchor likely reintroduced.
#diagram-color-guidedoes not exist in the current tutorial template, so this link target is likely invalid. Please align the anchor with an existing heading or add the missing section incontent_templates/template-tutorial.md.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content_templates/template-how-to.md` at line 30, The relref link "[Diagram Color Guide]({{< relref \"content_templates/template-tutorial.md#diagram-color-guide\" >}})" in template-how-to.md points to a non-existent anchor; either update the relref to match an existing heading ID in content_templates/template-tutorial.md (adjust the fragment after the # to the exact heading slug used there) or add a heading titled "Diagram Color Guide" (which will generate the diagram-color-guide anchor) to template-tutorial.md so the link resolves; locate the link text "[Diagram Color Guide]" in template-how-to.md and the headings in template-tutorial.md (or add the new heading) to make them consistent.
🧹 Nitpick comments (1)
content_templates/template-tutorial.md (1)
183-184: Remove duplicate concept link placeholder.Both bullets are identical placeholders; keep one and use the second for a different related concept or remove it to avoid noise.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@content_templates/template-tutorial.md` around lines 183 - 184, Remove the duplicate placeholder bullet that uses the pattern [Concept: <name>]({{< relref "docs/concepts/<file>.md" >}}) so only one concept link remains; either delete the second identical line or replace it with a different related concept (e.g., a distinct name/file) to avoid duplicate placeholders in the template.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In `@content_templates/template-how-to.md`:
- Line 30: The relref link "[Diagram Color Guide]({{< relref
\"content_templates/template-tutorial.md#diagram-color-guide\" >}})" in
template-how-to.md points to a non-existent anchor; either update the relref to
match an existing heading ID in content_templates/template-tutorial.md (adjust
the fragment after the # to the exact heading slug used there) or add a heading
titled "Diagram Color Guide" (which will generate the diagram-color-guide
anchor) to template-tutorial.md so the link resolves; locate the link text
"[Diagram Color Guide]" in template-how-to.md and the headings in
template-tutorial.md (or add the new heading) to make them consistent.
In `@content_templates/template-tutorial.md`:
- Line 152: Fix the malformed markdown heading by removing the unmatched
trailing bold markers: locate the heading line currently written as "### Verify
the result**" in content_templates/template-tutorial.md and change it to "###
Verify the result" so the heading is well-formed and no linting/rendering errors
occur.
---
Nitpick comments:
In `@content_templates/template-tutorial.md`:
- Around line 183-184: Remove the duplicate placeholder bullet that uses the
pattern [Concept: <name>]({{< relref "docs/concepts/<file>.md" >}}) so only one
concept link remains; either delete the second identical line or replace it with
a different related concept (e.g., a distinct name/file) to avoid duplicate
placeholders in the template.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e3177312-948d-4afb-a561-a51531560863
📒 Files selected for processing (3)
.github/config/wordlist.txtcontent_templates/template-how-to.mdcontent_templates/template-tutorial.md
<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
Adopt existing templates and add one for concepts.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* New concept template with a structured outline, mental-model guidance,
key-properties table, relationships, mermaid diagram spot, and a
publishing checklist
* Redesigned how-to template: clearer step headings, optional workflow
diagrams, standardized fenced blocks and titled "Expected output"
details, and symptom-based troubleshooting
* Updated tutorial template: focused learning outcomes, clearer semantic
steps, collapsible outputs, and streamlined next-steps guidance
* **Chores**
* Added a new token to the repository wordlist ("tos")
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Co-authored-by: Gerald Morrison (SAP) <gerald.morrison@sap.com> 4237328
What this PR does / why we need it
Adopt existing templates and add one for concepts.
Summary by CodeRabbit