Skip to content

Base Modifications

These are some opinionated modifications to default CSS for MkDocs desktop view.

Most sites looks the same: I also generally notice that the majority of MkDocs Material sites look very similar except for color palette changes and perhaps

  • Sidebar coloration ability added so it's easier to see the difference between main content and navigation -- like in Notion, Obsidian, Archbee or Docusaurus default themes. (Note on how this is achieved below.)
  • Selectors mapped out and added so changes can be made to anything
  • Our preferences 🎨:
    • tighten up line height
    • add vertical lines to show expanded folders like in Obsidian
    • Minimized letter spacing so narrower given small sidebar space
    • Sidebar colors added to left - but can allow for full right sidebar coloration as well

The default HTML for MkDocs Material employs html with max-width container that is center aligned, making it challenging to set a background color directly on a standard HTML element so a linear gradient is used on the body of the page and then an explicit body color is set to overlay and this ends up working out well! CSS code sample below. 

/* LIGHT */
body[data-md-color-scheme='default'] {
    background: linear-gradient(to right, #edf2f7 50%, #fff 50%);
}
body[data-md-color-scheme='default'] .md-content {
    background: #fff !important;
    border-left: 1px solid #e7e7e9;
}

Tables

  • Selectors added here
  • MkDocs Material, oddly, makes table font size smaller than other text and this will help fix that.
  • Our preferences 🎨:
    • Slightly altered padding to make it feel more consistent

Headers

  • MkDocs Material by default, also oddly, uses a thinner header font at something like 200-300
  • Selectors added to allow for easy alteration
  • Our preferences 🎨:
    • Changed from thin weight to bold 700 weight
    • Reduced margins above and below so paragraph text is closer

Page Header Index

  • Selectors to allow targeting here, similar to above
  • MkDocs Material default seems to keep the font-size the same as the body text
  • Our preferences
    • Smaller text to 12px so doesn't get confused (Archee inspired)
    • Hide "Table of Contents" text as seems necessary
    • Tighten line height
    • Adding vertical lines like in Obsidian and Archbee
  • Our preferences 🎨:
    • Hyperlinks underlined

Overall

  • Our preferences 🎨:
    • Uses "Inter" Font from Google
    • Reduced margin between bottom of header and start of text

Fonts

  • Loads GoogleFont "Inter" via extra_css options instead of default MkDocs loading mechanism so that more font weights can be loaded. MkDocs seemed to skip a few weights when using default loading. Therefore, the default font mechanism wad disable with font: false since if you don't do this MKDocs loads Roboto font by default, it seems

Other Ideas

  • Full width mode (had this before and removed it)
  • Move chevron left like in Cloudflare's docs - I already did this and the code is in here in overrides but I disabled it because it's hard to mantain and not that important
  • ⭐Changing MKDocs current breakpoint - annoyed it breaks so early but it's actually hard to change (Link to GIthub discussion on this)
  • Design ideas 🎨:
    • A design that looks more like Cloudflare's docs