Skip to content

Commit d0364fa

Browse files
claudiacodacyclaude
claudiacodacy
and
claude
authored
docs: introduce Mintlify-inspired Material theme (#2702)
* docs: introduce Mintlify-inspired Material theme * docs: address theme PR review feedback (source link + image hook) - source-link.html: filter empty path segments with Jinja `select` so an empty `page.meta.path` no longer produces a double slash in the URL (gemini-code-assist review). - image_metadata.py: open SVG files via a context manager before `iterparse` so the file descriptor is released immediately instead of waiting for GC (gemini-code-assist review). - image_metadata.py: match <img> tags without truncating on a '>' inside a quoted attribute value (codacy review). - image_metadata.py: log unreadable images at DEBUG (strict mode promotes WARNING to a build failure, and an unreadable image must never break the build) (codacy review). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: rebalance footer and keep support widget clear of it Marketing feedback on the footer: - Remove the "Full scan / Free trial / No credit card" tagline line: it has no value without a sign-up CTA, and the header already carries the "Get started" CTA. - Rebalance into three columns - brand tagline (left), links (center), copyright (right) - replacing the previous left/right split. - The floating Zendesk support widget overlapped the bottom-right links. The links are now centered and the footer reserves bottom space; docs-theme.js also flags <html> via an IntersectionObserver when the footer is visible so CSS lifts the widget above the footer (no-op if the widget is absent). Also folds in a review nitpick: replace the deprecated navigator.platform check with navigator.userAgentData.platform (falling back to platform, then the UA string) for the Cmd/Ctrl-K shortcut label. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: inline Ionicons SVGs at build time, drop the JS runtime The Ionicons web-component runtime hydrated <ion-icon> elements after page load and lazily fetched each SVG, causing a visible flash / layout shift on every page load. It also vendored ~11 opaque JS chunks that were hard to maintain. Icons must stay local (a CDN URL breaks on air-gapped self-hosted docs), so the fix is to inline the SVGs at build time. - Add theme/partials/icon.html: a Jinja macro icon(name, class="") that includes the source SVG from assets/vendor/ionicons/svg/<name>.svg and injects the shared "docs-icon" class + aria-hidden onto the <svg>. - Replace every <ion-icon> with an icon(...) call across header, search, palette, source, toc, path-item and nav-item partials (dynamic names for the palette toggle and sidebar_icons work as macro arguments). - Remove the two ionicons <script> includes from main.html and delete the 11 vendored ionicons JS chunks. The 27 source SVGs and the MIT LICENSE stay. - Retarget the ion-icon CSS selectors to svg (header.css) and add a .docs-icon base rule (base.css) mirroring the old default sizing and currentColor inheritance. Result: icons are server-rendered inline SVG - zero runtime JS, zero network fetches, no flash / layout shift, and trivially works offline. Verified with a strict mkdocs build: 0 <ion-icon> elements and no references to the deleted JS remain in the generated site; icons render as inline <svg class="docs-icon">. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: use a linear <img> regex to clear Codacy ReDoS gate The quote-aware <img> pattern added earlier tripped Codacy's Critical "inefficient regular expression" (ReDoS) check, failing the quality gate. Revert _IMAGE_TAG to the linear `<img\b[^>]*>` and instead insert the generated attributes right after the `<img` token (rather than before the closing `>`). The output stays valid even when the match stops early at a `>` inside an attribute value, which addresses the original truncation concern without a backtracking-prone regex. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: restructure footer to tagline-left, links + copyright right Drop the centered links column. The footer is now two regions: the tagline on the left (no longer bold) and the nav links followed by the copyright grouped together on the right (Pricing · Blog · Support · Privacy · ©). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: fix self-hosted sidebar icon and trim footer copyright - server-outline.svg declared fill="none" on the root <svg> instead of on its shapes. The theme's `.docs-icon { fill: currentColor }` rule overrides a root fill, so the shapes inherited currentColor and the icon rendered as a filled blob. Move fill="none" onto each shape (matching every other outline icon) so it renders as an outline again. - Footer copyright now drops the " - Automated code review" suffix (stripped in the footer template only; the site-wide config.copyright is unchanged so the RSS feed etc. keep the full string). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: keep header visible and stop scroll jump when search opens Opening search triggers Material's scroll-lock, which sets the body to position: fixed. That dragged the sticky header (and its theme toggle) out of view and behind the full-screen search overlay, and read as the page jumping upward. - Pin the header to the viewport (position: fixed, z-index above the search overlay) while search is open, so the whole navbar — including the theme toggle — stays visible and interactive. - Give the search box enough top margin to clear the pinned header. - Focus the search input with { preventScroll: true } so opening search never nudges the scroll position. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 4747675 commit d0364fa

84 files changed

Lines changed: 2098 additions & 192 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/styles/config/vocabularies/Codacy/accept.txt‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ Hadolint
4646
Hardcoded
4747
hostname
4848
hotfix
49+
hotfixes
50+
Ionicons
4951
Jira
5052
jq
5153
jscpd
@@ -69,6 +71,7 @@ PVC
6971
Pylint
7072
remark-lint
7173
Revive
74+
Roboto
7275
Rollout
7376
rollout
7477
RuboCop
@@ -85,6 +88,7 @@ SpotBugs
8588
SQLint
8689
Staticcheck
8790
Stylelint
91+
SVGs
8892
SwiftLint
8993
Tailor
9094
tooltip
@@ -94,7 +98,12 @@ TSQLLint
9498
unassigns
9599
unfollow
96100
unignore
101+
Unignoring
102+
unignoring
103+
unignored
104+
unreferenced
97105
vacuumdb
106+
vendored
98107
Visualforce
99108
VSCode
100109
webserver

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
# MkDocs build dir
22
site/
33

4+
# Python bytecode generated while running MkDocs hooks
5+
__pycache__/
6+
*.py[cod]
7+
48
# OS generated files
59
.DS_Store
610

@@ -28,4 +32,3 @@ tools/*.csv
2832

2933
#Ignore vscode AI rules
3034
.github/instructions/codacy.instructions.md
31-

‎CONTRIBUTING.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
You're welcome to make fixes and changes to the documentation. Here are a few steps to get you going:
44

55
- [Authoring documentation pages](#authoring-documentation-pages)
6+
- [Working on the documentation theme](#working-on-the-documentation-theme)
67
- [Releasing a new Codacy Self-hosted documentation version](#releasing-a-new-codacy-self-hosted-documentation-version)
78
- [Updating an existing Codacy Self-hosted documentation version](#updating-an-existing-codacy-self-hosted-documentation-version)
89
- [Applying documentation hotfixes to existing chart releases](#applying-documentation-hotfixes-to-existing-chart-releases)
@@ -39,6 +40,75 @@ You're welcome to make fixes and changes to the documentation. Here are a few st
3940
mkdocs serve
4041
```
4142
43+
### Working on the documentation theme
44+
45+
The documentation uses the installed `mkdocs-material` package with a small,
46+
Codacy-owned theme layer in [`theme/`](theme/). This is
47+
the current theme source of truth. Don't copy, modify, or renew the legacy
48+
`submodules/codacy-mkdocs-material` clone when changing this site's theme.
49+
50+
The theme is intentionally plain CSS and minimal Jinja overrides:
51+
52+
- [`theme/stylesheets/tokens.css`](theme/stylesheets/tokens.css)
53+
defines the Codacy color tokens and Material color mappings.
54+
- The visual styling lives in [`theme/stylesheets/`](theme/stylesheets/),
55+
split by concern (`base`, `header`, `navigation`, `content`, `home`,
56+
`footer`, `layout`, `responsive`) and loaded in that order via `extra_css`.
57+
The files are plain, comment-free CSS; keep a rule in the file that matches
58+
its concern, and keep `extra_css` in cascade order (it layers over the
59+
Material package, so order and specificity are what make an override win).
60+
- [`theme/main.html`](theme/main.html) and its
61+
[`partials/`](theme/partials/) retain only the overrides and
62+
integrations that Codacy needs.
63+
- [`mkdocs.yml`](mkdocs.yml) connects this layer through `theme.custom_dir`
64+
and loads the small supporting browser scripts and stylesheets.
65+
66+
Several partials under [`theme/partials/`](theme/partials/) (for example
67+
`nav-item.html`, `header.html`, `search.html`, and `toc.html`) are derived from
68+
the equivalent templates in the `mkdocs-material` version pinned in
69+
[`requirements.txt`](requirements.txt) and then trimmed to Codacy's needs. They
70+
are coupled to that version's markup, CSS class names, and JavaScript component
71+
contracts, so **bumping `mkdocs-material` requires re-diffing these partials
72+
against the new upstream templates** and re-testing search, the palette toggle,
73+
and navigation. Pin the package to an exact version and treat an upgrade as a
74+
deliberate task, not an incidental dependency bump.
75+
76+
There is no front-end build step. Edit the CSS, Jinja partials, or supporting
77+
JavaScript directly, then use the normal MkDocs preview:
78+
79+
```bash
80+
mkdocs serve
81+
```
82+
83+
The theme self-hosts the Inter and Roboto Mono font files under
84+
`theme/assets/fonts/`; it doesn't contact a third-party font service. Keep the
85+
font license beside those assets when updating them.
86+
87+
Icons are provided by Ionicons, also vendored locally under
88+
`theme/assets/vendor/ionicons/` (the runtime loader plus only the SVGs the theme
89+
references) so the docs render fully offline and don't depend on a third-party
90+
CDN—this matters for Self-hosted installations. When you add an
91+
`<ion-icon name="…">` or a `sidebar_icons` entry, copy the matching
92+
`svg/<name>.svg` from the Ionicons package into that folder; unreferenced icons
93+
are intentionally not vendored. Keep the Ionicons license beside the assets.
94+
95+
The `theme/hooks/image_metadata.py` hook adds intrinsic dimensions and safe
96+
loading hints to local documentation images at build time. Authors normally use
97+
standard Markdown image syntax; explicit HTML image attributes are preserved
98+
when a page needs an exception.
99+
100+
Before opening a pull request that changes the theme, build with warnings
101+
treated as errors and check representative pages in the local preview:
102+
103+
```bash
104+
mkdocs build --strict
105+
```
106+
107+
Check a Cloud page and, when relevant, a Self-hosted page. Also check light and
108+
dark color schemes, desktop and narrow mobile widths, search, the version
109+
picker, and any changed content component. Preserve analytics, feedback,
110+
preview and Self-hosted notices, source metadata, and existing URLs.
111+
42112
### Markdown conventions
43113
44114
Follow these Markdown conventions when editing the documentation:

‎docs/account/emails.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ To manage the email addresses associated with your account and your email notifi
88

99
Codacy automatically links to your Codacy account the email addresses from the Git provider associated with your current session. On the **Emails** page, you can verify which email addresses are linked to your Codacy account.
1010

11-
!!! notes
11+
!!! note
1212
- For **GitHub**, if you have [email privacy enabled](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address?platform=mac#about-commit-email-addresses) on the provider, Codacy doesn't show your private emails and uses another available email address when displaying your personal details on lists, search filters, or activity.
1313
- Codacy doesn't allow you to have one email associated with more than one GitHub account. You can manage your [associated emails in the provider GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account).
1414

‎docs/assets/images/codacy-docs-logo-light.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎docs/assets/images/codacy-docs-logo.svg‎

Lines changed: 1 addition & 1 deletion
Loading

‎docs/assets/includes/nav-multistep-quickstart.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,33 @@
1-
<nav class="nav-multistep">
1+
<nav class="nav-multistep" aria-label="Getting started guide">
22
<p>This page is part of the following guided path:</p>
33
<ol>
4-
<li class="{% if page.meta.nav_step == 0 %}nav-multistep__step--active{% endif %}">
4+
<li{% if page.meta.nav_step == 0 %} aria-current="step"{% endif %}>
55
{% if page.meta.nav_step == 0 %}
6-
<p>
6+
<span>
77
Adding your first repository
8-
</p>
8+
</span>
99
{% else %}
1010
<a href="/getting-started/codacy-quickstart#adding-your-first-repository">
1111
Adding your first repository
1212
</a>
1313
{% endif %}
1414
</li>
15-
<li class="{% if page.meta.nav_step == 1 %}nav-multistep__step--active{% endif %}">
15+
<li{% if page.meta.nav_step == 1 %} aria-current="step"{% endif %}>
1616
{% if page.meta.nav_step == 1 %}
17-
<p>
17+
<span>
1818
Configuring your repository
19-
</p>
19+
</span>
2020
{% else %}
2121
<a href="/getting-started/configuring-your-repository#configuring-your-repository">
2222
Configuring your repository
2323
</a>
2424
{% endif %}
2525
</li>
26-
<li class="{% if page.meta.nav_step == 2 %}nav-multistep__step--active{% endif %}">
26+
<li{% if page.meta.nav_step == 2 %} aria-current="step"{% endif %}>
2727
{% if page.meta.nav_step == 2 %}
28-
<p>
28+
<span>
2929
Integrating Codacy with your Git workflow
30-
</p>
30+
</span>
3131
{% else %}
3232
<a href="/getting-started/integrating-codacy-with-your-git-workflow#integrating-codacy-with-your-git-workflow">
3333
Integrating Codacy with your Git workflow
@@ -36,4 +36,3 @@
3636
</li>
3737
</ol>
3838
</nav>
39-

0 commit comments

Comments
 (0)