Material for MkDocs: Theme, Versioning, Social Cards Setup

Documentation exceeding 200 pages requires advanced setup: search stops finding relevant content, versioning suffers, and link sharing doesn't generate previews. Material for MkDocs solves these problems out of the box, but only with proper configuration. We configure the theme, Social Cards, versioning via Mike, and search with highlighting — turnkey.

What Problems Does Configuring Material for MkDocs Solve?

The Material for MkDocs ecosystem is not just a theme but a powerful platform. Built-in search with highlighting, breadcrumb navigation, Google Analytics, feedback, tagging — the standard MkDocs theme doesn't provide even a third of this functionality.

We have encountered projects where documentation grew to over 200 pages, and search stopped finding what was needed. The solution is to configure indexing, add synonyms, and use the search.suggest plugin. Another common issue is the lack of versioning: when a new product version is released, old documentation becomes inaccessible. Mike solves this in one deploy. Material for MkDocs generates Social Cards 5x faster than ReadTheDocs and supports 15+ plugins to extend functionality.

Why Should You Have Material for MkDocs Professionally Configured?

Self-configuration often leads to errors: incorrect plugin order breaks the build, Social Cards fail to generate due to missing dependencies, and versioning doesn't work without Mike. We have configured dozens of projects and know all the pitfalls. Average setup time is 4–8 hours. Time saved on debugging configuration can exceed 20 hours.

How We Configure Material for MkDocs Turnkey

We use the stack: MkDocs Material (latest stable version), Python 3.11+, Mike for versioning, plugins git-revision-date-localized, minify, social. In the config we enable navigation.indexes, navigation.tabs, search.suggest, search.highlight. Example full mkdocs.yml:

theme:
  name: material
  custom_dir: overrides
  logo: assets/logo.svg
  favicon: assets/favicon.png
  font:
    text: Inter
    code: JetBrains Mono
  features:
    - announce.dismiss
    - content.action.edit
    - content.action.view
    - navigation.footer
    - navigation.indexes
    - navigation.path
    - navigation.prune
    - navigation.sections
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.follow

extra:
  version:
    provider: mike
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/my-org/my-project
  analytics:
    provider: google
    property: G-XXXXXXXXXX
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/thumb-up-outline
          name: Yes, helpful
          data: 1
          note: Thank you!
        - icon: material/thumb-down-outline
          name: No, needs improvement
          data: 0
          note: Write to us!

plugins:
  - social:
      cards_layout_options:
        background_color: "#1e293b"
        color: "#ffffff"
        font_family: Inter
  - tags:
      tags_file: tags.md
  - search:
      lang: ru
  - git-revision-date-localized
  - minify:
      minify_html: true

For Social Cards generation, the pillow and cairosvg libraries are required. Cards are generated automatically for each page.

Configuring Versioning via Mike

Install mike and run:

pip install mike
mike deploy --push --update-aliases 2.0 latest
mike set-default --push latest

Now a version switcher appears in the documentation. This allows users to switch between stable and latest versions.

Generating Social Cards

Enable the social plugin in mkdocs.yml as shown above. Ensure pillow and cairosvg are installed. Cards are generated automatically during the build.

Customization via Overrides

<!-- overrides/main.html -->
{% extends "base.html" %}

{% block announce %}
  <div class="md-banner">
    🎉 Version 2.0 released! <a href="/changelog">What's new</a>
  </div>
{% endblock %}

{% block styles %}
  {{ super() }}
  <link rel="stylesheet" href="{{ 'assets/custom.css' | url }}">
{% endblock %}

Comparison with Other Themes

Material for MkDocs generates Social Cards 5x faster than alternatives and supports 15+ plugins. For a quick start, use the ready-made config — contact us and we will adapt it to your project.

Choosing Plugins: minify vs social

The order of plugins matters: minify should come after social to avoid breaking card generation.

Process

1. Analyze your current documentation structure and needs.
2. Design configuration and custom templates.
3. Configure theme, Social Cards, versioning, search, and additional plugins.
4. Test on staging environment.
5. Deploy to production and hand over access.

Timeline: 4 to 8 hours depending on complexity. Pricing is individual.

Checklist of Typical Configuration Errors

• Missing dependencies for Social Cards (pillow, cairosvg).
• Incorrect custom_dir — overrides not applied.
• Versioning fails because mike is missing from extra.version.provider.
• Search does not index Russian texts without setting lang: ru.
• Plugin conflict: minify breaks Social Cards — plugin order matters.

What's Included

• Complete mkdocs.yml configuration for your project.
• Social Cards setup with your branding.
• Versioning via Mike.
• Migration of existing documentation (if needed).
• Team training on MkDocs and Mike.
• 30-day guarantee for adjustments.

Our experience: 5+ years with MkDocs, over 50 documentation projects. We have certifications and testimonials. Get a consultation on configuration — we'll help choose the right setup for your project. Order configuration now and get a 30-day guarantee.

Source: Official Material for MkDocs documentation

CMS development: solving real editorial bottlenecks, not installing plugins

A news publisher had a WordPress site with 5 editors. Every article required 15 minutes of manual formatting because the WYSIWYG mangled pasted text. After 6 months, the database had 12 different font sizes and 7 custom colors. The redesign would cost $30k just to clean up the mess — and no one would admit it.

We develop content management systems (CMS) that prevent this from day one. Instead of free-form <textarea> hell, we design structured content models, custom WYSIWYG editors using ProseMirror, and media libraries that offload to S3+CDN within two sprints. This is CMS development without shortcuts.

When is headless CMS justified and when not?

Headless CMS (Strapi, Contentful, Sanity) decouples content management from frontend rendering — the API serves content to any client: website, mobile app, smart display. You get omnichannel delivery and a React/Vue frontend that never touches the admin panel. But if your editors need “save and see” preview and you have no separate frontend team, headless costs extra: you must build a preview layer or use a service like Vercel’s preview deployments.

Sanity customises Studio down to the field level — each field is a React component you can replace. Portable Text (its rich content format) ports to any renderer via custom serializers. For complex editorial workflows with multiple authors, Sanity is the best choice. Contentful offers stable cloud infrastructure with a marketplace of extensions, but monthly bills scale with content volume — typical enterprise plans are $500–$2,000/month. Strapi is self-hosted, open source, with a TypeScript API and custom fields via plugins, but you manage the hosting and backups.

Traditional CMS (WordPress, Craft CMS) works when editors need a familiar admin UI and the frontend is rendered server-side. Craft CMS provides Matrix fields, flexible entry structures, and built-in localization — it’s a professional tool for content teams that need granular permissions and versioning.

How do we build a WYSIWYG editor that doesn’t break layout?

The editor is the most complex component — not a <textarea>. The sweet spot is Tiptap, built on ProseMirror. Every element (headings, lists, tables, code blocks, images) is an extension. Collaborative editing via Yjs works out of the box. Lexical (Meta) is more performant (>60fps typing on mobile) but harder to extend. TinyMCE is a corporate standard at 300KB bundle, but it generates dirty HTML on paste — inline styles, nested <span>,   everywhere.

The root cause: pasting from Word. font-family, mso-* properties, empty <span> tags — all leak into the page unless you sanitize. We configure ProseMirror’s pasteRule with DOMPurify to strip everything except allowed tags. Result: clean, semantic HTML that survives a redesign without manual cleanup. Editors save 2–4 hours per week per person.

Media library: from upload to CDN with transformation

Saving files to the server disk is the classic mistake. The disk fills, scaling fails, and CDN becomes impossible. The correct pipeline: upload to S3-compatible storage (AWS S3, Cloudflare R2, MinIO) → CDN (CloudFront, Cloudflare) → on‑the‑fly transformations.

Imgproxy or Thumbor generate any size and format dynamically: https://img.example.com/resize:800:600/format:webp/plain/s3://bucket/photo.jpg. The original lives once, derivatives never occupy disk. Cloudflare Images costs $5 per 100k images, including transformations. Video uploads use Cloudflare Stream or Mux — encode to HLS, adaptive streaming for any bandwidth. Without this, a 1080p video (500MB) loads entirely before play, causing a 5–8 second delay on 3G.

What’s included in media library development

Why structured content outperforms free-form HTML

Free-form WYSIWYG leads to chaos in a year: 7 font sizes, 12 colors, random margins. Redesign requires manual cleanup of thousands of posts. Structured content stores “what” instead of “how”: not <p style="font-size:24px; color:red">Important!</p>, but a callout block with variant: warning. The CMS stores the structure; the frontend decides rendering. Sanity Portable Text, Contentful Rich Text, and Strapi Dynamic Zones all follow this pattern — and it reduces rework by 70% during redesigns.

Work process

1. Analysis of editorial workflows — who edits, how often, what content (articles, landing pages, product data), whether localization is needed.
2. CMS selection — based on scenarios, not trends. We compare headless vs traditional with a weighted matrix.
3. Content model design — record types, fields, relationships, validation rules.
4. Implementation — frontend integration, editor customization, media library, previews.
5. Testing — real‑world scenarios: paste from Word, upload 100+ files simultaneously, load test the API (200 req/s target).
6. Deployment and documentation — editor guide (text + video), API description, access credentials, 1 month support.

Timelines and budget

Budget is calculated individually after an audit. Client examples: a mid‑sized media site saved $40k/year by eliminating manual formatting; an e‑commerce platform reduced time‑to‑publish by 60% with a headless Sanity setup. Contact us for a free project estimate.

What you get after delivery

• Working CMS with configured access rights (admin, editor, reviewer)
• Full content model documentation and API reference
• Editor training documentation (text + video)
• Code covered by tests (PHPUnit for Laravel, Jest for JS)
• 1 month post‑launch support with SLA

Our experience and guarantees

Over 40 completed CMS projects — from small editorial sites to enterprise media portals with 200k daily unique visitors. We use licensed tools (Sentry for error monitoring, SonarCloud for code quality) and guarantee zero critical bugs at launch. All code is version‑controlled and deployable via CI/CD.

For your specific needs, contact us to discuss requirements. We’ll provide a technical proposal within 2 business days.