feat: implement server-side objective letter badge injection

Author: jgeluk

docs-overrides/partials/content.html

@@ -35,9 +35,18 @@
   page title (or respectively site name) is used as the main headline.
 -->
 {% if not "\x3ch1" in page.content %}
+{% if page.meta.letter_prefix %}
+<div class="objective-header-with-badge">
+<span class="objective-badge-standalone" data-letter="{{ page.meta.letter_prefix }}"></span>
+
+<h1>{{ page.title | d(config.site_name, true)}}</h1>
+
+</div>
+{% else %}
 <h1>{{ page.title | d(config.site_name, true)}}</h1>
 {% endif %}
 {% endif %}
+{% endif %}
 
 <!-- Page content -->
 {% if page.meta.letter_prefix %}

docs/javascripts/objective-badges.js

@@ -16,9 +16,7 @@
 
   function injectBadge() {
     // Check if letter_prefix exists in page metadata
-    const metaScript = document.getElementById(
-      'page-meta-letter-prefix'
-    );
+    const metaScript = document.getElementById('page-meta-letter-prefix');
     if (!metaScript) {
       return; // No letter_prefix on this page
     }
@@ -27,10 +25,7 @@
     try {
       letterPrefix = JSON.parse(metaScript.textContent);
     } catch (e) {
-      console.error(
-        '[objective-badges] Failed to parse letter_prefix',
-        e
-      );
+      console.error('[objective-badges] Failed to parse letter_prefix', e);
       return;
     }
 
@@ -39,25 +34,21 @@
     }
 
     // Find the first H1 in the main content area
-    const mainContent = document.querySelector(
-      '.md-content__inner, article'
-    );
+    const mainContent = document.querySelector('.md-content__inner, article');
     if (!mainContent) {
       return;
     }
 
     // Check if H1 is already wrapped in objective-header-with-badge
-    const existingWrapper = mainContent.querySelector(
-      '.objective-header-with-badge'
-    );
+    const existingWrapper = mainContent.querySelector('.objective-header-with-badge');
     if (existingWrapper) {
       return; // Already has badge, skip
     }
 
     // Find the first H1
     const firstH1 = mainContent.querySelector('h1:first-of-type');
     if (!firstH1) {
-      return; // No H1 found
+      return;
     }
 
     // Create the badge span
@@ -77,23 +68,30 @@
     wrapper.appendChild(document.createTextNode('\n\n'));
   }
 
-  function initPage() {
-    // Small delay to ensure DOM is ready
-    setTimeout(injectBadge, 0);
+  function scheduleInjection() {
+    // Use requestIdleCallback to run when browser is idle (after rendering)
+    if (window.requestIdleCallback) {
+      requestIdleCallback(() => {
+        injectBadge();
+      }, { timeout: 500 });
+    } else {
+      // Fallback for browsers without requestIdleCallback
+      setTimeout(injectBadge, 200);
+    }
   }
 
-  // Handle Material for MkDocs instant loading
+  // Subscribe to document$ observable for instant loading
   if (window.document$ && window.document$.subscribe) {
     document$.subscribe(() => {
-      initPage();
+      scheduleInjection();
     });
   }
 
-  // Initial page load
+  // Initial call
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', initPage);
+    document.addEventListener('DOMContentLoaded', scheduleInjection);
   } else {
-    initPage();
+    scheduleInjection();
   }
 })();
 

docs/main.py

@@ -0,0 +1,49 @@
+import re
+
+def define_env(env):
+    "Hook function"
+
+    @env.macro
+    def test123(page):
+        list = []
+        while page.next_page:
+            list.append(page.next_page)
+            page = page.next_page
+        return list
+
+
+def on_page_content(html, page, config, files):
+    """
+    Inject objective letter badge before the first H1 heading.
+    This runs after markdown is converted to HTML.
+    """
+    # Check if page has letter_prefix in frontmatter
+    if not hasattr(page, 'meta') or 'letter_prefix' not in page.meta:
+        return html
+    
+    letter_prefix = page.meta['letter_prefix']
+    if not letter_prefix or not isinstance(letter_prefix, str):
+        return html
+    
+    # Find the first H1 tag and wrap it with the badge
+    # Pattern: <h1 ... > ... </h1>
+    h1_pattern = r'(<h1[^>]*>)(.*?)(</h1>)'
+    
+    def replace_first_h1(match):
+        opening_tag = match.group(1)
+        h1_content = match.group(2)
+        closing_tag = match.group(3)
+        
+        # Create the badge wrapper HTML
+        badge_html = f'''<div class="objective-header-with-badge">
+<span class="objective-badge-standalone" data-letter="{letter_prefix}"></span>
+
+{opening_tag}{h1_content}{closing_tag}
+
+</div>'''
+        return badge_html
+    
+    # Replace only the first H1
+    modified_html = re.sub(h1_pattern, replace_first_h1, html, count=1, flags=re.DOTALL)
+    
+    return modified_html

mkdocs.yml

@@ -74,6 +74,10 @@ extra_javascript:
   - javascripts/mermaid.js
   - javascripts/darkable-objects.js
   - javascripts/objective-badges.js
+
+hooks:
+  - docs/main.py
+
 plugins:
   - include-markdown
   - git-revision-date-localized: