Utvecklingsjournal — MkDocs Comments/Chrome (2025-08-28)#

Den här journalen sammanfattar vårt felsökningsarbete kring Comments-panelen i högerspalten för “Source Code”-vyerna i Material for MkDocs, där layouten fungerade bra i Firefox men visade märkliga problem i Chrome. Målet var att se till att kolumnbredden för högerspalten nyttjades korrekt även i Chrome samt att kodmarkeringen (docstrings) blev tydlig, utan att påverka annan layout. På grund av tidsskäl pausas arbetet tills vidare - det fungerar utmärkt i Firefox-baserade webbläsare.

Ajdö till Zen som primär browser - halloj Edge - Chrome baserad men har native tabs i sidebar och fungerar helt ok med linux - och ger smidigare stöd för att utveckla mot viewTransition API:et.

Chromebaserad

Firefoxbaserad

Utgångsläge#

  • Tema: Material for MkDocs, egna overrides under overrides/.

  • Comments-panelen injiceras av overrides/partials/toc.html i sidopanelen till höger (secondary sidebar).

  • Egen CSS för Comments: docs/stylesheets/comments.css och docs/stylesheets/comments_layout.css.

  • Kodmarkering (docstrings m.m.): docs/stylesheets/highlight-docstrings.css.

  • JavaScript för att ladda kommentarsinnehållet: docs/javascripts/comments.js (hämtar HTML från docs/assets/comments/code/<lang>/<code_rel_path>.html).

Symptombeskrivning#

  • I Firefox: högerspalten nyttjade bredden rätt, både kodblock och brödtext i Comments visades och fyllde utrymmet.

  • I Chrome: högerspalten var bred, men brödtext i Comments använde inte hela bredden. Kodblock såg “bredare” ut (ledde ibland till horisontell scrollbar), medan vanlig text såg hopklämd ut.

  • Vid ett tillfälle syntes Comments inte alls i högerspalten efter aggressiva CSS-förändringar (senare återställt).

Hypoteser och observationer#

  • Flex + scroll-min-content i Chrome: Nestlade scroll-containrar i flexlayouter gör ofta att Chrome beräknar min-bredd som min-content, vilket kan trycka ihop kolumnen.

  • Material-temats ToC begränsar ofta högersidans “inner”-container för läsbarhet. Chrome följer denna begränsning striktare än Firefox.

  • “Measure” för text: Material använder en variabel (ungefär 45–70ch) för textraders längd. Kodblock följer inte den begränsningen — därav skillnaden.

Åtgärder vi testade (kronologiskt)#

  1. Läsning av konfiguration och overrides

  • Granskade mkdocs.yml, overrides/main.html, overrides/partials/toc.html samt relaterad CSS/JS.

  1. Ta bort extra wrappers i toc.html

  • Tog bort ytterligare nivå .md-sidebar__scrollwrap/.md-sidebar__inner kring Comments för att undvika nestlade scroll-containrar.

  • Effekt: Viss förbättring i struktur, men Chrome begränsade fortfarande brödtextens bredd.

  • Lades tillbaka senare då alternativa försök gav regressioner.

  1. Min-bredd-guard och flexjusteringar

  • Satte min-width: 0 på relevanta flexbarn (.md-content, .md-sidebar--secondary).

  • Justerade flex-shrink genom att ändra flex: 0 1 ... respektive 0 0 ... för högerspalten.

  • Testade overflow-x: visible på scrollwrap som nödlösning.

  • Effekt: Dämpade men ej robust lösning i Chrome.

  1. Flytta ToC till vänster (toc.integrate)

  • Aktiverade theme.features: [toc.integrate] i mkdocs.yml för att avsätta hela högerspalten för Comments.

  • Ändrade toc.html så bara Comments renderades i högerspalten.

  • Effekt: För stora sidoeffekter, ungick regressioner och bröt UX. Återställdes.

  1. Grid i högerspalten

  • Testade att styra .md-sidebar--secondary .md-sidebar__inner med CSS Grid för att tydligt separera ToC och Comments i egna rader.

  • Effekt: Bättre struktur, men gav följdproblem med scroll och var känsligt i Chrome. Återställdes.

  1. Justering av typografisk measure för Comments

  • Försökte först med --md-typeset-measure: 100% på #__comments-pane (ogiltigt värde i vissa kontexter).

  • Bytte till giltig enhet: --md-typeset-measure: 999ch samt max-width: none. Syfte: låta brödtexten nyttja hela kolumnen.

  • Laddade tillfälliga debugutskrifter via ?cmdebug=1 i comments.js för att läsa ut sidebar/inner/pane-bredd. I Chrome sågs t ex pane: 276px när inner var ~710px, vilket pekade på kvarvarande max-width-kläm.

  • Effekt: Delvis, men krävde kraftiga !important-regler för att vinna över temat — detta ledde till risk för regressioner (Comments dök ej upp i vissa vyer). Återställdes.

  1. Forcera bredd med !important

  • Tvingade .md-sidebar__scrollwrap och .md-sidebar__inner till width: 100% !important, samt satte ToC till en explicit maxbredd.

  • Effekt: Gav utrymme, men på bekostnad av robusthet. Comments försvann ibland i vissa vyer. Återställdes.

  1. Test- och debuginnehåll

  • Lade till en tillfällig testsida (docs/source/test/test_layout.md) och Comments-HTML (SV/EN) för att återskapa edge-cases med långa paths/URL:er/ord.

  • Effekt: Bra för reproduktion, men plockades bort efteråt.

  1. Kodmarkering (docstrings och kommentarer)

  • Krav: Endast docstrings ska markeras som hela rader (hl_lines). Inline-kommentarer (# …) ska inte få bakgrund.

  • Vi experimenterade med:

    • Tog bort token-bakgrund för .sd (docstring-strängar) och lät hl_lines sköta radmarkeringens bakgrund.

    • Säkerställde att .c/.c1 (kommentarer) ej fick bakgrund.

    • Upptäckte “förskjutna” docstring-radintervall i docs/source/src/app/main.md. Jämförde mot AST och noterade att statiska hl_lines var inaktuella.

    • La temporärt in auto-generering av wrappers före build (körde AST för att skriva nya hl_lines), men avstod för att inte störa nuvarande pipeline.

  • Slutinsikt: hl_lines måste hållas i synk med koden, annars blir radbakgrundsfärgen fel — CSS är inte roten till felet här.

Nuvarande status (paus)#

  • Layouten är återställd till stabil version före experimenten.

  • Comments renderas igen i högerspalten.

  • Vi pausar vidare layoutändringar i Chrome tills vi har planerat ett mer kontrollerat angreppssätt, utan att riskera regressions i andra vyer.

Lärdomar#

  • Chrome hanterar flex + nestlade scroll-containrar och typografisk “measure” strängare än Firefox.

  • --md-typeset-measure kräver giltig längdenhet (t.ex. ch), inte procent.

  • Att försöka vinna över temats max-width med !important blir snabbt skört; håll dig inom temats DOM/klass-struktur där möjligt.

  • För docstring-markering ligger roten till felet i hl_lines-intervallen — dessa ska hållas synkade automatisk istället för workarounds i CSS.

Förslag inför nästa iteration#

  • Antingen:

    1. Integrera ToC i vänster-navigatorn (Material’s toc.integrate) för att reservera hela högerspalten till Comments, eller

    2. Bygg en robust grid-layout för högerspalten (utan extra wrappers) och ge ToC respektive Comments varsin tydlig rad, med min-width: 0.

  • Sätt --md-typeset-measure endast för #__comments-pane och bekräfta att inga andra selektorer (från temat) åter klämmer max-width.

  • Ha en minimal, mätbar debug-funktion (utan att röra prod) för att snabbt mäta sidebar/inner/pane-bredd.

  • Automatisera hl_lines-regenerering i build-steget så docstring-rader alltid matchar källkoden.

Sammanfattning#

Vi har systematiskt testat markup, CSS och JS för att få Chrome att använda Comments-kolumnens bredd lika effektivt som Firefox. Flera vägar förbättrade, men skapade risk för regressioner i navigation och scrollbeteenden. Vi har därför valt att pausa vidare ändringar tills vi kan planera ett kontrollerat ingrepp (via toc.integrate eller grid) och komplettera med automatisk generering av hl_lines så kodmarkeringen ligger i fas även när koden ändras.

Senast uppdaterad: 2025-08-28 Avsikt: Dokumentera felsökningen samt beslut om tillfällig paus och att återuppta med en mer robust lösning.