Feature/docs ia revamp : Information Architecture Revamp and Streamlining. #102
Conversation
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
|
@Mike-4-prog is attempting to deploy a commit to the idan lodzki's projects Team on Vercel. A member of the Team first needs to authorize it. |
📝 WalkthroughWalkthroughAdds and reorganizes documentation: many new MDX/MD files (getting-started, integrations, alerts, dashboards, contributing, FAQ, glossary), deletes several legacy getting-started/core-features docs, updates the sidebar navigation, and makes small workflow and CSS tweaks. Changes
Possibly related PRs
Suggested labels
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
🤖 Fix all issues with AI agents
In `@opsimate-docs/docs/contributing/index.md`:
- Line 6: Header and body use the incorrect capitalization "Opsimate"; replace
every instance of the product name with the official "OpsiMate" (e.g., update
the heading "Contributing to Opsimate" and all other occurrences of the literal
string "Opsimate") to ensure consistent branding across the document; perform a
global find-and-replace for "Opsimate" → "OpsiMate", review surrounding
punctuation/casing for sentence starts, and run a quick pass to confirm no
remaining mismatched instances.
- Line 57: The README contains inconsistent local preview ports: one occurrence
uses "http://localhost:8080" and another uses "http://localhost:3000"; determine
the actual port the docs server uses (check the dev server config or npm script
that runs the docs) and update both strings to the correct port (replace
"http://localhost:8080" and "http://localhost:3000" so they match the real
server port) and ensure any related instructions (npm vs Docker) reflect that
single, correct port.
- Around line 40-47: The example imports and uses a non-existent Callout
component (import Callout from '@site/src/components/Callout' and the
<Callout>...</Callout> usage); remove that import and either replace the JSX
with an existing component such as CookieConsent or GoogleAnalytics (update/add
the appropriate import) or convert the example to native HTML (e.g., a
blockquote/div with a descriptive class) so the example runs without a
missing-component runtime error.
In `@opsimate-docs/docs/dashboards/saved-dashboards.mdx`:
- Around line 35-36: The line "**Save View**: Click \"Save Current View\" and
provide a name" is orphaned and should be removed or integrated into the
preceding numbered steps; either delete that standalone line or move it into the
step that describes saving the dashboard (e.g., append as a sub-step or convert
into a properly formatted bullet under the step that ends with "you will be able
to see your saved dashboard") and ensure MDX formatting matches the surrounding
numbered list and heading styles so it no longer reads disconnected.
In `@opsimate-docs/docs/faq/index.md`:
- Line 43: The hardcoded localhost URLs for the "Adding Providers" link (and the
other occurrence at line 149) should be changed to relative paths; replace
"http://localhost:3000/docs/providers-services/providers/add-provider" with
"/docs/providers-services/providers/add-provider" (and any other hardcoded
"http://localhost:3000/..." instances) so the links use relative paths
consistent with other links like "/docs/alerts/adding-alerts"; update the link
targets in the markdown for the "Adding Providers" link text and the second
occurrence accordingly.
In `@opsimate-docs/docs/getting-started/quick-start.mdx`:
- Around line 132-133: The two markdown links `[See configuration
guide](configuration)` and `[System requirements](system-requirements)` (and the
duplicate `[configuration guide](configuration)`) are broken because those pages
were consolidated into this quick-start; update those link targets to valid
anchors or remove them. Replace those three occurrences with internal section
anchors (e.g., link to `#configuration` or `#system-requirements` headings
within this page) or plain text references if the sections are nearby, ensuring
the link text remains accurate (search for the exact strings `See configuration
guide`, `System requirements`, and `configuration guide` to locate each
occurrence).
- Around line 101-104: The document uses an unsupported admonition type
`:::success`; replace the `:::success` opening and its matching closing with a
supported type such as `:::tip` or `:::info` so Docusaurus 3.9.2 renders it
correctly (locate the `:::success` block around the "OpsiMate is now running..."
text and update both the start and end markers to `:::tip` or `:::info`).
In `@opsimate-docs/docs/glossary/index.md`:
- Line 15: The document jumps from a top-level title to "### A-C" (heading level
skip) and has overlapping/misplaced alphabetical sections ("D-F" vs "E–F",
"Providers" missing prefix, "M–O" containing S-terms); change all alphabetical
group headers like "### A-C" to second-level headers "## A–C" (and similarly for
"D–F", "E–F", "M–O") to fix MD001, reconcile overlapping ranges by choosing
consistent ranges (e.g., "D–E" and "F–G" or unify to non-overlapping spans) and
rename "Providers" to include its alphabetical range (or move it under the
correct range), and relocate S-prefixed entries currently under "M–O" into the
proper "S" group so each term falls under the correct alphabetical header.
- Line 19: The glossary contains hardcoded localhost URLs (e.g., the "TV Mode"
link) which will break in production; update every anchor href that starts with
"http://localhost:3000" to use a relative path (e.g.,
"/docs/alerts/tv-mode-view") so links are environment-agnostic; search for
occurrences of "http://localhost:3000" in the document and replace them with the
corresponding absolute-to-root relative paths, ensuring link text (like "TV
Mode") and other referenced pages keep their targets unchanged.
In `@opsimate-docs/docs/integrations/gcp.mdx`:
- Around line 20-22: Replace the incorrect code-fence language identifier
"pgsql" with "text" (or remove it) for the webhook URL code blocks so they
render as plain URLs; specifically update the code fences shown in the gcp
integration example (the block containing
"http://localhost:3001/api/v1/alerts/custom/gcp?api_token={your_api_token}") and
apply the same change to the second identical block later in the file (the block
at the other occurrence around lines 48-50).
In `@opsimate-docs/docs/integrations/uptime-kuma.mdx`:
- Around line 22-24: Change the fenced code blocks that use the wrong language
identifier `pgsql` to `text` for the Uptime Kuma webhook URL examples;
specifically update both code blocks that contain the URL
"http://localhost:3001/api/v1/alerts/custom/uptime-kuma?api_token={your_api_token}"
so their opening fences read ```text instead of ```pgsql to ensure correct
highlighting.
In `@opsimate-docs/docs/integrations/zabbix.mdx`:
- Around line 121-123: Replace the non-standard admonition marker ":::important"
with a supported Docusaurus admonition such as ":::caution" or ":::info" in the
block that contains the `zabbix_url` guidance so the admonition renders
correctly; locate the text block containing ":::important" and change it to a
standard admonition type (e.g., ":::caution") while preserving the existing
message about setting `zabbix_url`.
In `@opsimate-docs/src/css/custom.css`:
- Around line 74-94: Replace the hardcoded black text colors in
.theme-doc-sidebar-item-link and .theme-doc-sidebar-item-category (and any other
sidebar selectors using color: `#000000`) with a CSS variable (e.g.,
--sidebar-text-color) and use that variable in the selectors instead of `#000000`;
then define --sidebar-text-color in the global/light theme (fallback to `#000000`)
and override it in the dark theme to a light color so sidebar text remains
visible in dark mode; keep the .menu__link--active styling but switch its color
to use a variable (e.g., --sidebar-active-color) or an appropriate existing
--ifm variable so active link color also respects dark theme.
🧹 Nitpick comments (7)
opsimate-docs/docs/getting-started/introduction.mdx (1)
42-45: Minor: Hyphenate compound adjectives.Per static analysis hints, "bare metal" (line 42) and "3rd party" (line 45) should be hyphenated when used as compound adjectives modifying a noun.
📝 Suggested fix
-- From bare metal servers to Kubernetes clusters +- From bare-metal servers to Kubernetes clusters - AWS Lambda functions and cloud services - Docker containers and virtual machines -- All your monitoring tools and 3rd party integrations +- All your monitoring tools and third-party integrationsopsimate-docs/docs/getting-started/quick-start.mdx (1)
69-71: Missing blank line before heading.A blank line is typically required before a heading in Markdown for proper parsing and consistent rendering.
📝 Suggested fix
private_keys_path: "/app/data/private-keys"
Next Steps
After configuring OpsiMate:
</details> </blockquote></details> <details> <summary>opsimate-docs/docs/integrations/gcp.mdx (1)</summary><blockquote> `62-67`: **Remove trailing blank lines.** Multiple trailing blank lines at the end of the file should be removed for consistency. </blockquote></details> <details> <summary>opsimate-docs/docs/integrations/uptime-kuma.mdx (1)</summary><blockquote> `68-73`: **Remove trailing blank lines.** Multiple trailing blank lines at the end of the file should be removed for consistency. </blockquote></details> <details> <summary>opsimate-docs/src/css/custom.css (1)</summary><blockquote> `186-196`: **Fragile selector using hashed class name.** `.admonitionContent_pbrs` appears to be a build-generated class name that may change between Docusaurus versions or builds. Consider using a more stable selector. <details> <summary>Suggested alternative</summary> ```diff -/* ---------- Links inside admonitions ---------- */ -.admonitionContent_pbrs p a { +/* ---------- Links inside admonitions ---------- */ +.theme-admonition-content p a, +[class*="admonitionContent"] p a { text-decoration: underline; text-decoration-color: transparent; font-weight: 500; transition: text-decoration-color 0.3s ease-in-out; } -.admonitionContent_pbrs p a:hover { +.theme-admonition-content p a:hover, +[class*="admonitionContent"] p a:hover { text-decoration-color: currentColor; }opsimate-docs/docs/dashboards/saved-dashboards.mdx (2)
1-4: Consider adding explicit title in frontmatter.The frontmatter lacks a
titlefield. While Docusaurus can infer it from the h1 heading, explicit titles ensure consistent behavior in navigation and SEO.Proposed fix
--- +title: Saved Dashboards sidebar_position: 4 ---
16-25: Consider using the existing CSS class for image styling.The inline styles duplicate what's already available in
custom.cssvia the.doc-imageclass (lines 179-184). Using the class improves maintainability.Proposed refactor
<div style={{textAlign: 'center', margin: '30px 0'}}> <img src="/img/saved-dashboards.png" alt="Saved Dashboards" - style={{width: '900px', maxWidth: '100%', height: 'auto', borderRadius: '8px', boxShadow: '0 4px 12px rgba(0,0,0,0.15)'}} + className="doc-image" + style={{width: '900px', maxWidth: '100%', height: 'auto'}} />
Comment on lines
+40
to
+47
| import Callout from '@site/src/components/Callout'; | ||
| import Tabs from '@theme/Tabs'; | ||
| import TabItem from '@theme/TabItem'; | ||
|
|
||
| <Callout type="info"> | ||
| This is an important note. | ||
| </Callout> | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -type f -name "*Callout*" | head -20Repository: OpsiMate/documentation
Length of output: 48
🏁 Script executed:
fd -t f "Callout" --extension jsx --extension tsx --extension js --extension ts 2>/dev/null | head -20Repository: OpsiMate/documentation
Length of output: 48
🏁 Script executed:
rg "Callout" --type jsx --type tsx --type js --type md -A 2 -B 2 2>/dev/null | head -50Repository: OpsiMate/documentation
Length of output: 48
🏁 Script executed:
find src/components -type f 2>/dev/null | head -20Repository: OpsiMate/documentation
Length of output: 48
🏁 Script executed:
ls -la src/ 2>/dev/null || echo "src directory not found"Repository: OpsiMate/documentation
Length of output: 89
🏁 Script executed:
git ls-files | grep -i "component" | head -20Repository: OpsiMate/documentation
Length of output: 206
🏁 Script executed:
ls -la opsimate-docs/src/components/Repository: OpsiMate/documentation
Length of output: 378
🏁 Script executed:
rg "Callout" opsimate-docs/ 2>/dev/nullRepository: OpsiMate/documentation
Length of output: 365
Remove or replace the non-existent Callout component.
The import statement import Callout from '@site/src/components/Callout'; references a component that does not exist in opsimate-docs/src/components/. The only available components are CookieConsent and GoogleAnalytics. Contributors following this example will encounter a runtime error. Either create the Callout component or replace the example with code using an existing component or native HTML.
🤖 Prompt for AI Agents
In `@opsimate-docs/docs/contributing/index.md` around lines 40 - 47, The example
imports and uses a non-existent Callout component (import Callout from
'@site/src/components/Callout' and the <Callout>...</Callout> usage); remove
that import and either replace the JSX with an existing component such as
CookieConsent or GoogleAnalytics (update/add the appropriate import) or convert
the example to native HTML (e.g., a blockquote/div with a descriptive class) so
the example runs without a missing-component runtime error.
opsimate-docs/src/css/custom.css
Outdated
Comment on lines
74
to
94
| .theme-doc-sidebar-item-link { | ||
| font-size: 15px; | ||
| line-height: 1.6; | ||
| color: #000000; | ||
| font-weight: 500; | ||
| } | ||
|
|
||
| .navbar-icon-link:hover, | ||
| .footer-community-icon-link:hover, | ||
| .navbar__items button.clean-btn:hover { | ||
| background-color: rgba(57, 73, 171, 0.3); | ||
| transform: translateY(-1px); | ||
| .theme-doc-sidebar-item-link:hover { | ||
| color: #3949ab; /* Indigo hover */ | ||
| } | ||
|
|
||
| .navbar-icon-link:hover .navbar-icon, | ||
| .footer-community-icon-link:hover .footer-community-icon { | ||
| filter: invert(35%) sepia(100%) saturate(800%) hue-rotate(240deg); | ||
| .menu__link--active { | ||
| font-weight: 600; | ||
| color: #5c6bc0 !important; /* Indigo active link */ | ||
| } | ||
|
|
||
| .theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__list-item-collapsible__label { | ||
| font-size: 15px; | ||
| font-weight: 600; | ||
| color: #000000; | ||
| } |
There was a problem hiding this comment.
Sidebar colors may have contrast issues in dark mode.
Lines 77 and 93 hardcode color: #000000 for sidebar items, but dark theme (lines 23-30) sets `--ifm-background-color: `#000000. This creates invisible text in dark mode.
Proposed fix using CSS variables
.theme-doc-sidebar-item-link {
font-size: 15px;
line-height: 1.6;
- color: `#000000`;
+ color: var(--ifm-font-color-base);
font-weight: 500;
}
.theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__list-item-collapsible__label {
font-size: 15px;
font-weight: 600;
- color: `#000000`;
+ color: var(--ifm-font-color-base);
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| .theme-doc-sidebar-item-link { | |
| font-size: 15px; | |
| line-height: 1.6; | |
| color: #000000; | |
| font-weight: 500; | |
| } | |
| .navbar-icon-link:hover, | |
| .footer-community-icon-link:hover, | |
| .navbar__items button.clean-btn:hover { | |
| background-color: rgba(57, 73, 171, 0.3); | |
| transform: translateY(-1px); | |
| .theme-doc-sidebar-item-link:hover { | |
| color: #3949ab; /* Indigo hover */ | |
| } | |
| .navbar-icon-link:hover .navbar-icon, | |
| .footer-community-icon-link:hover .footer-community-icon { | |
| filter: invert(35%) sepia(100%) saturate(800%) hue-rotate(240deg); | |
| .menu__link--active { | |
| font-weight: 600; | |
| color: #5c6bc0 !important; /* Indigo active link */ | |
| } | |
| .theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__list-item-collapsible__label { | |
| font-size: 15px; | |
| font-weight: 600; | |
| color: #000000; | |
| } | |
| .theme-doc-sidebar-item-link { | |
| font-size: 15px; | |
| line-height: 1.6; | |
| color: var(--ifm-font-color-base); | |
| font-weight: 500; | |
| } | |
| .theme-doc-sidebar-item-link:hover { | |
| color: `#3949ab`; /* Indigo hover */ | |
| } | |
| .menu__link--active { | |
| font-weight: 600; | |
| color: `#5c6bc0` !important; /* Indigo active link */ | |
| } | |
| .theme-doc-sidebar-item-category > .menu__list-item-collapsible > .menu__list-item-collapsible__label { | |
| font-size: 15px; | |
| font-weight: 600; | |
| color: var(--ifm-font-color-base); | |
| } |
🤖 Prompt for AI Agents
In `@opsimate-docs/src/css/custom.css` around lines 74 - 94, Replace the hardcoded
black text colors in .theme-doc-sidebar-item-link and
.theme-doc-sidebar-item-category (and any other sidebar selectors using color:
`#000000`) with a CSS variable (e.g., --sidebar-text-color) and use that variable
in the selectors instead of `#000000`; then define --sidebar-text-color in the
global/light theme (fallback to `#000000`) and override it in the dark theme to a
light color so sidebar text remains visible in dark mode; keep the
.menu__link--active styling but switch its color to use a variable (e.g.,
--sidebar-active-color) or an appropriate existing --ifm variable so active link
color also respects dark theme.
Mike-4-prog
force-pushed
the
feature/docs-ia-revamp
branch
from
ca3c58b to
2905ffc
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@opsimate-docs/docs/getting-started/introduction.mdx`:
- Around line 77-80: The links in the Getting Started list (e.g., the "Deploy
OpsiMate" link and the others "Add Providers", "Configure Services", "Create
Alerts") are relative to the current document path and produce broken URLs;
update each link target to be root-relative by prefixing a leading slash (for
example change "getting-started/quick-start" to "/getting-started/quick-start"
and do the same for "providers-services/providers/add-provider",
"providers-services/services/add-services", and "monitoring/setting-up-alerts")
so they resolve correctly site-wide.
- Replace hardcoded localhost URLs with relative paths - Fix code block language identifiers (pgsql → text) - Replace :::important with :::caution admonition
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@opsimate-docs/docs/faq/index.md`:
- Line 43: The link for "Adding Providers" has a duplicated path segment
(`/docs/docs/`) causing a broken URL; edit the markdown link text that currently
reads "👉 Learn more: [Adding
Providers](/docs/docs/providers-services/providers/add-provider)" and change the
href to use a single `/docs/` prefix so it becomes
"/docs/providers-services/providers/add-provider" (locate the link by the
visible anchor text "Adding Providers").
- Line 149: Update the markdown link target that incorrectly contains a
duplicated "docs" segment: change the link target
"/docs/docs/alerts/tv-mode-view" (the link with text "TV Mode View") to the
correct path "/docs/alerts/tv-mode-view" so the anchor points to the intended
page.
In `@opsimate-docs/docs/glossary/index.md`:
- Line 19: Fix the broken internal links that have a duplicated "/docs/docs/"
prefix by replacing occurrences like "/docs/docs/alerts/tv-mode-view" with the
correct "/docs/alerts/tv-mode-view"; update the same pattern for the other
reported instances (lines referenced 42, 96, 159) by searching for "/docs/docs/"
in the glossary file and removing the extra "/docs/" so all links use a single
"/docs/" prefix.
- Fix relative links in introduction.mdx (add /docs/ prefix) - Fix duplicate /docs/docs/ paths in FAQ and Glossary - Update Node.js version in workflow to 20 (Docusaurus 3.9.2 requirement) - Fix localhost URLs in integrations and glossary - Fix code block language identifiers (pgsql → text) - Fix admonition type (:::important → :::caution) - Resolve merge conflicts from IA revamp
- Fix branding: 'Opsimate' → 'OpsiMate' in contributing guide - Remove non-existent Callout component import and usage - Fix inconsistent port numbers in local preview instructions - Remove orphaned content in saved-dashboards.mdx - Fix dark mode contrast in custom.css sidebar text
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@opsimate-docs/src/css/custom.css`:
- Around line 22-28: The dark-theme CSS incorrectly sets --ifm-background-color
and --ifm-navbar-background-color to var(--ifm-font-color-base) which is then
redefined to a light color; update the [data-theme="dark"] block to assign
explicit dark values (e.g., a dark surface for --ifm-background-color and a
matching dark/nav color for --ifm-navbar-background-color) while keeping
--ifm-font-color-base and --ifm-heading-color as the light text colors so text
remains readable; change only the variable values in the [data-theme="dark"]
selector (referencing --ifm-background-color, --ifm-background-surface-color,
--ifm-font-color-base, --ifm-heading-color, and --ifm-navbar-background-color)
to ensure background and navbar are dark and font variables remain light.
🧹 Nitpick comments (1)
opsimate-docs/src/css/custom.css (1)
18-18: Consider using explicit color instead of font color variable for navbar background.Using
var(--ifm-font-color-base)for--ifm-navbar-background-coloris semantically confusing since font color typically represents text, not backgrounds. While this works in light mode (both resolve to#000000), it reduces code clarity.♻️ Suggested improvement
- --ifm-navbar-background-color: var(--ifm-font-color-base); + --ifm-navbar-background-color: `#000000`;
- Set explicit dark colors for background and navbar (#000000) - Ensure dark theme has dark backgrounds with light text - Fix variable dependency issue that caused light background in dark mode
- Fix duplicate --ifm-background-color and --ifm-navbar-background-color lines - Keep only the explicit dark color values (#000000) - Ensure dark theme works correctly
- Remove old .md files that conflict with new .mdx versions: - saved-dashboards.md (duplicate of .mdx) - gcp.md (duplicate of .mdx) - uptime-kuma.md (duplicate of .mdx) - zabbix.md (duplicate of .mdx) - Fix Docusaurus error: 'Docs should have distinct ids' - Keep only the updated .mdx versions for consistency
- Remove references to deleted files: core-features, configuration, deploy, system-requirements - Add new IA structure: Providers & Services, updated categories - Align sidebar with actual document files - Previously fixed: duplicate .md files, dark theme CSS, localhost URLs
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
What this PR does
Summary by CodeRabbit