Skip to content
This repository was archived by the owner on Apr 13, 2026. It is now read-only.

Update docs templates#755

Merged
jakobmoellerdev merged 8 commits into
open-component-model:mainfrom
morri-son:update-docs-templates
Mar 17, 2026
Merged

Update docs templates#755
jakobmoellerdev merged 8 commits into
open-component-model:mainfrom
morri-son:update-docs-templates

Conversation

@morri-son

@morri-son morri-son commented Mar 13, 2026

Copy link
Copy Markdown
Contributor

What this PR does / why we need it

Adopt existing templates and add one for concepts.

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")

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>
@morri-son morri-son requested a review from a team as a code owner March 13, 2026 17:02
@netlify

netlify Bot commented Mar 13, 2026

Copy link
Copy Markdown

Deploy Preview for open-component-model ready!

Name Link
🔨 Latest commit ff4ab54
🔍 Latest deploy log https://app.netlify.com/projects/open-component-model/deploys/69b96c887894450008858389
😎 Deploy Preview https://deploy-preview-755--open-component-model.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Mar 13, 2026

Copy link
Copy Markdown
📝 Walkthrough

Walkthrough

Adds 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

Cohort / File(s) Summary
Concept Template
content_templates/template-concept.md
Adds a new concept-documentation template with front matter and a structured outline (What is it?, Why, How it works with Mermaid, sub-concepts, properties table, relationships, usage guidance, and a comprehensive before-publishing checklist).
How-To Template
content_templates/template-how-to.md
Refactors steps to semantic headings, adds optional Workflow/Mermaid, normalizes code and output into details wrappers, consolidates signing-methods tabs, restructures Troubleshooting into Symptom/Cause/Fix, and converts Next steps/Related docs to narrative placeholders.
Tutorial Template
content_templates/template-tutorial.md
Shortens overview, introduces "What You'll Learn", moves expected outputs into details blocks, restyles steps as semantic headings, updates Mermaid guidance/diagram, and shifts content toward modular, outcome-focused placeholders.
Wordlist
.github/config/wordlist.txt
Appends the token tos to the repository wordlist (single-line additive change).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

kind/chore

Suggested reviewers

  • frewilhelm
  • fabianburth

Poem

🐇 I hopped through headings, tidy and spry,

Details tucked neatly, outputs shy.
New concept pages, steps made bright,
A small token added, tucked out of sight—
Hooray for docs that help readers fly!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
Title check ❓ Inconclusive The title 'Update docs templates' is vague and generic, using non-descriptive terms that don't convey specific information about the changeset. Consider a more specific title such as 'Add concept template and refactor documentation templates' to better reflect the primary changes.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
📝 Coding Plan
  • Generate coding plan for human review comments

Comment @coderabbitai help to get the list of available commands and usage tips.

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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

📥 Commits

Reviewing files that changed from the base of the PR and between a8b5449 and d593d7a.

📒 Files selected for processing (3)
  • content_templates/template-concept.md
  • content_templates/template-how-to.md
  • content_templates/template-tutorial.md

Comment thread content_templates/template-how-to.md
Comment thread content_templates/template-how-to.md Outdated
Comment thread content_templates/template-tutorial.md
Comment thread content_templates/template-tutorial.md Outdated
On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
.github/config/wordlist.txt (1)

470-470: Avoid adding overly generic short tokens to the global wordlist.

tos is 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

📥 Commits

Reviewing files that changed from the base of the PR and between d593d7a and fb817e8.

📒 Files selected for processing (2)
  • .github/config/wordlist.txt
  • content_templates/template-tutorial.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • content_templates/template-tutorial.md

matthiasbruns
matthiasbruns previously approved these changes Mar 16, 2026
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>

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

♻️ Duplicate comments (2)
content_templates/template-tutorial.md (1)

152-152: ⚠️ Potential issue | 🟡 Minor

Fix 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 | 🟡 Minor

Broken relref anchor likely reintroduced.

#diagram-color-guide does 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 in content_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

📥 Commits

Reviewing files that changed from the base of the PR and between fb817e8 and ff4ab54.

📒 Files selected for processing (3)
  • .github/config/wordlist.txt
  • content_templates/template-how-to.md
  • content_templates/template-tutorial.md

@jakobmoellerdev jakobmoellerdev merged commit 4237328 into open-component-model:main Mar 17, 2026
10 checks passed
ocmbot Bot pushed a commit that referenced this pull request Mar 17, 2026
<!-- 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
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants