Migrate from MkDocs

Build an MkDocs / Material for MkDocs project with epresso — live from mkdocs.yml, or imported once into docs.toml.

epresso builds an existing MkDocs (or Material for MkDocs) project with no content changes. You can try it straight from your mkdocs.yml, then switch to a docs.toml when you are ready.

Try it

Run epresso docs . in the directory that holds mkdocs.yml:

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
cd my-mkdocs-projectepresso docs .               # serve on :4321epresso docs . --out site/   # or write a static build

epresso reads mkdocs.yml live and renders docs_dir with the docs theme. Settings it can't map are printed as warnings; nothing is written.

Switch over

  


    
        
    
    
    
        
            
                bash
            
        
        
        
    







  
epresso import mkdocs        # mkdocs.yml → docs.tomlepresso docs .

epresso import mkdocs writes the same settings into a docs.toml. From then on epresso docs . uses docs.toml (it tells you it is ignoring mkdocs.yml). It won't overwrite an existing docs.toml unless you pass --force. Pass --theme ../my-theme to record your own theme.

What carries over

mkdocs.yml epresso
site_name title
site_url, site_description [site] url, description
repo_url, edit_uri the page source links
docs_dir the docs source
nav the sidebar (nav on the source); pages not in nav are built but not listed
extra_css, extra_javascript loaded after the theme's CSS
redirects plugin redirect_maps [[redirects]]
search, minify plugins built in
social plugin epresso_social (on in the docs theme)
blog plugin epresso_blog (on in the docs theme), same URLs
optimize plugin epresso_optimize (on in the docs theme)
theme ignored — the look comes from the docs theme or --theme

Markdown syntax

The docs theme enables the epresso_mkdocs plugin. Any other site can turn it on with plugins = ["epresso_mkdocs"] in site.toml. It renders:

  • admonitions (!!! note "Title") and collapsible blocks (???, ???+)
  • content tabs (=== "Label"), also inside admonitions and list items
  • fenced code nested in admonitions, tabs and lists
  • attr_list (## Title { #id .class }, Paragraph {: .lead }, [link](x){ .button }) and md_in_html (<div>)
  • snippets (--8<-- "path/file.md"), resolved against the project directory; a path outside the project is an error
  • definition lists, footnotes, abbreviations (*[HTML]: …), task lists, ==mark==, ^^insert^^, ^sup^, ~sub~ and ++ctrl+alt+del++ keys

The HTML uses Material's class names (.admonition, .admonition-title, details.tip, .tabbed-set, .keys), so extra_css written for Material keeps working.

Limits

Markdown inside <div> must be separated from the tags by blank lines. Icons and emoji (:material-…:), math (arithmatex) and Mermaid diagrams are not supported yet; epresso names any unsupported extension.

Plugins without an equivalent yet

mkdocstrings and macros are reported as warnings and skipped. The rest of the site still builds.