Add code annotations with Akemi as the marker - #347
Conversation
Enables Material's content.code.annotate feature (plus md_in_html, which annotation tooltips need for block-level content). Instead of the theme's default (+) marker, the annotation button is Akemi: the theme's single-color mask is dropped and the cheerful Akemi already shipped as the site logo is drawn directly, anchored to the bottom of the line so she peeks over the text. She grows slightly on hover and while the tooltip is open, replacing the theme's tint-and-rotate effect. No pages are annotated yet; docs changes that use annotations come in a follow-up PR.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughChangesCode annotation presentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches✨ Simplify code
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: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/assets/stylesheets/extra.css`:
- Line 57: Update the background asset URL in the stylesheet to use the relative
path ../images/ui/akemi/001_cheerful.png instead of the root-relative /assets
path, preserving the existing background positioning and sizing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: ec0b5362-ed78-4b9e-98db-365e98000e61
📒 Files selected for processing (2)
docs/assets/stylesheets/extra.cssmkdocs.yml
| .md-annotation__index::after { | ||
| -webkit-mask-image: none; | ||
| mask-image: none; | ||
| background: url("/assets/images/ui/akemi/001_cheerful.png") center bottom / contain no-repeat; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
rg -n '^(site_url|use_directory_urls|extra_css):|001_cheerful\.png' \
mkdocs.yml docs/assets/stylesheets/extra.css || true
fd -a -t f '001_cheerful\.png$' docs/assetsRepository: wled/WLED-Docs
Length of output: 437
🏁 Script executed:
#!/bin/bash
set -eu
printf 'mkdocs.yml relevant lines:\n'
sed -n '1,90p' mkdocs.yml | cat -n
printf '\nextra.css relevant lines:\n'
sed -n '1,90p' docs/assets/stylesheets/extra.css | cat -n
printf '\nMkDocs configuration files:\n'
fd -a -t f '^(mkdocs|docs|site-)?\.ya?ml$' .Repository: wled/WLED-Docs
Length of output: 6982
🌐 Web query:
MkDocs site_url custom_css_url extra_css directory_urls site_url extra_css base path
💡 Result:
In MkDocs, the site_url and use_directory_urls settings dictate how your site handles URLs and navigation, while extra_css is used to inject custom styles into your documentation [1][2][3]. site_url The site_url setting defines the canonical URL of your site [1][4]. It is critical for generating correct canonical links in the HTML header and is often required by plugins [1][5]. If your site is hosted in a subdirectory (e.g., https://example.com/foo/), you must include that path in the site_url (e.g., https://example.com/foo/) [1][2]. This setting also influences how mkdocs serve mounts your site locally [1][2]. If you are building documentation for local file system viewing (e.g., using the file:// scheme), you should set site_url to an empty string ("") [6]. use_directory_urls The use_directory_urls setting determines the file structure and linking style of your generated HTML files [3][7]. - When true (default), Markdown files are mapped to an index.html file inside a directory (e.g., about.md becomes about/index.html), resulting in clean URLs like /about/ [3][8][7]. - When false, Markdown files are mapped to a single HTML file of the same name (e.g., about.md becomes about.html) [3][8][7]. This style is useful when browsing documentation directly from a local file system where directory-based index files may not resolve correctly [6][7]. extra_css The extra_css setting is a list used to include custom CSS files in your generated documentation [9][10][3]. To use it: 1. Place your CSS file (e.g., style.css) inside your docs_dir (the folder containing your Markdown files) [9][10]. 2. Add the file path to your mkdocs.yml configuration: extra_css: - style.css These files are added to the generated HTML document after the page content, allowing you to override or add to the theme's existing styles [9][10].
Citations:
- 1: https://mkdocs.readthedocs.io/en/stable/user-guide/configuration/
- 2: https://www.mkdocs.org/user-guide/configuration/
- 3: https://github.com/mkdocs/mkdocs/blob/master/mkdocs/config/defaults.py
- 4: https://mkdocs.readthedocs.io/en/859/user-guide/configuration/
- 5: https://squidfunk.github.io/mkdocs-material/creating-your-site/
- 6: https://www.mkdocs.org/user-guide/deploying-your-docs/
- 7: https://mkdocs.readthedocs.io/en/0.14.0/user-guide/configuration/
- 8: https://www.mkdocs.org/dev-guide/api/
- 9: https://mkdocs.readthedocs.io/en/stable/user-guide/customizing-your-theme/
- 10: https://www.mkdocs.org/user-guide/customizing-your-theme/
🌐 Web query:
"MkDocs" "Use relative URLs for CSS assets" "site_url" "static_url"
💡 Result:
MkDocs is designed to use relative URLs for all internal links and static assets, ensuring that the generated site remains functional regardless of where it is hosted (e.g., in a subdirectory or at the root) [1][2][3]. For CSS assets, you generally do not need to manually configure them as absolute URLs. Instead, you manage them as follows: 1. Standard Extra CSS: Place your CSS files (e.g., in a stylesheets/ directory) within your docs/ folder [4][5]. Then, reference them in your mkdocs.yml using the extra_css configuration [1][4][5]: extra_css: - stylesheets/extra.css MkDocs will automatically handle the necessary relative paths to these files in the generated HTML [1][6]. 2. Theme Customizations: If you are overriding a theme or including assets directly in a custom template, you can use the base_url variable (or the url Jinja2 filter) to ensure links remain relative to the root of the site [7][8]: or 3. Handling Subdirectories: If your site is hosted in a subdirectory (e.g., https://example.com/project/), you should set the site_url in mkdocs.yml to reflect this, such as site_url: https://example.com/project/ [1]. MkDocs uses this configuration to correctly calculate relative paths, ensuring that links point to the correct location relative to the server root or the deployment path [1][7]. If you find that MkDocs is not automatically rewriting a specific URL (for example, inside raw HTML blocks), note that MkDocs' automatic link-fixing features primarily apply to standard Markdown links and theme templates; they do not always process hard-coded links within raw HTML [9]. In such cases, using relative paths that account for the directory structure of the built site is the standard approach [9].
Citations:
- 1: https://www.mkdocs.org/user-guide/configuration/
- 2: https://www.mkdocs.org/user-guide/writing-your-docs/
- 3: https://www.mkdocs.org/user-guide/deploying-your-docs/
- 4: https://www.mkdocs.org/user-guide/customizing-your-theme/
- 5: https://squidfunk.github.io/mkdocs-material/customization/
- 6: https://stackoverflow.com/questions/52316446/mkdocs-does-not-work-properly-with-custom-url-path
- 7: How to configure CSS path absolute? mkdocs/mkdocs#3153
- 8: https://mkdocs.readthedocs.io/en/0.14.0/user-guide/styling-your-docs/
- 9: Relative URLS in embedded HTML are not rewritten to account for directory URLs mkdocs/mkdocs#3618
🌐 Web query:
"Material for MkDocs" "custom_css_url" "url" extra_css
💡 Result:
To include custom CSS in Material for MkDocs, you should use the standard MkDocs configuration option extra_css in your mkdocs.yml file [1][2]. There is no specific custom_css_url setting; extra_css is the authorized method for loading additional stylesheets [2][3]. Steps to add custom CSS: 1. Create a CSS file in your project, typically within the docs directory (e.g., docs/stylesheets/extra.css) [1][4]. 2. Reference this file in your mkdocs.yml using the extra_css key [1][2]: yaml extra_css: - stylesheets/extra.css Paths provided in extra_css are relative to the docs_dir [2]. You can also provide absolute URLs or external paths if you are loading CSS from a CDN [5]. For more extensive theme modifications, such as overriding templates or partials, Material for MkDocs also supports a custom_dir configuration in mkdocs.yml, which allows you to override specific theme files by placing them in a designated folder [1][6]. However, for simple style tweaks, using extra_css is the recommended and most straightforward approach [1][3].
Citations:
- 1: https://squidfunk.github.io/mkdocs-material/customization/
- 2: https://www.mkdocs.org/user-guide/configuration/
- 3: https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/
- 4: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
- 5: https://mkdocs-material.github.io/examples/fonts-custom/
- 6: https://github.com/squidfunk/mkdocs-material/blob/master/docs/customization.md
Use a base-path-safe asset URL.
The stylesheet is loaded from docs/assets/stylesheets/extra.css, but this background URL is root-relative and currently points to /assets/images/ui/akemi/001_cheerful.png. Since the asset is tracked at docs/assets/images/ui/akemi/001_cheerful.png, use ../images/ui/akemi/001_cheerful.png so the generated path remains correct for non-root deployments.
Proposed fix
- background: url("/assets/images/ui/akemi/001_cheerful.png") center bottom / contain no-repeat;
+ background: url("../images/ui/akemi/001_cheerful.png") center bottom / contain no-repeat;📝 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.
| background: url("/assets/images/ui/akemi/001_cheerful.png") center bottom / contain no-repeat; | |
| background: url("../images/ui/akemi/001_cheerful.png") center bottom / contain no-repeat; |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/assets/stylesheets/extra.css` at line 57, Update the background asset
URL in the stylesheet to use the relative path
../images/ui/akemi/001_cheerful.png instead of the root-relative /assets path,
preserving the existing background positioning and sizing.
netmindz
left a comment
netmindz
left a comment
There was a problem hiding this comment.
thank you for your contribution
|
@softhack007 what do you think of this one? I really like it. I do something similar with Apollo docs. |
|
@bharvey88 looks nice, I'm just wondering will it also work on mobile devices? Like a pad with touch but without a mouse pointer? |
Yes it works on mobile- you can see it live on our wiki here: https://wiki.apolloautomation.com/products/ESPHome-Starter-Kit/setup/first-steps/ |
3 participants
This enables Material's code annotations, numbered notes that open in a tooltip from a small marker in a code block or paragraph, and restyles the marker: instead of the theme's default (+) sign, the marker is the cheerful Akemi already used as the site logo, anchored to the bottom of the line so she peeks over the text. She grows slightly (1.15x) on hover and while a tooltip is open, replacing the theme's tint-and-rotate effect.
Config side: the
content.code.annotatetheme feature plus themd_in_htmlextension annotations rely on. The marker styling is pure CSS inextra.cssusing the existing logo asset; no new files or images.This PR deliberately adds only the capability and styling. No pages are annotated yet; a follow-up PR will start using annotations in the docs. Preview of what it looks like on an annotated page:
Summary by CodeRabbit
Summary by CodeRabbit