{"library":"mkdocs","title":"MkDocs","description":"MkDocs is a fast, simple, and downright gorgeous static site generator that's geared towards building project documentation with Markdown. It converts a directory of Markdown files and a YAML configuration into a static website. The current version is 1.6.1, and it maintains an active release cadence with several patch and minor releases per year to address bugs and introduce new features.","status":"active","version":"1.6.1","language":"en","source_language":"en","source_url":"https://github.com/mkdocs/mkdocs","tags":["documentation","static-site-generator","markdown","developer-tools"],"install":[{"cmd":"pip install mkdocs","lang":"bash","label":"Install MkDocs"},{"cmd":"pip install mkdocs[i18n]","lang":"bash","label":"Install with internationalization support"}],"dependencies":[{"reason":"Provides internationalization (i18n) support, installed with `mkdocs[i18n]` extra.","package":"babel","optional":true}],"imports":[{"note":"Commonly imported by plugin developers to define event handlers.","symbol":"plugins","correct":"import mkdocs.plugins"},{"note":"Used for programmatic access to MkDocs configuration, less common for typical users.","symbol":"config","correct":"from mkdocs import config"}],"quickstart":{"code":"import os\n\n# Create a new MkDocs project\nos.system(\"mkdocs new my-docs-project\")\n\n# Change into the project directory\nos.chdir(\"my-docs-project\")\n\n# Start the development server (runs in the background for this example)\n# In a real scenario, you'd run this from your terminal and visit http://127.0.0.1:8000\nprint(\"Run 'mkdocs serve' in your terminal in the 'my-docs-project' directory to preview your site.\")\nprint(\"To open in browser automatically: 'mkdocs serve --open'\")","lang":"python","description":"This quickstart demonstrates how to create a new MkDocs project and start its built-in development server. The `mkdocs new` command scaffolds a basic project structure with a `mkdocs.yml` configuration file and a `docs/` directory for your Markdown content. The `mkdocs serve` command then launches a local server with live-reloading for development."},"warnings":[{"fix":"Update plugin/theme code to expect either strings or dictionary objects in `config.extra_javascript`. When reading values, cast to `str(value)` or check `isinstance` for dictionary attributes. Refer to the official documentation for the new structure.","message":"The `config.extra_javascript` option in `mkdocs.yml` changed behavior in version 1.5.0. It is no longer strictly a list of strings but can now contain mappings with keys like `type`, `async`, and `defer`. Plugins or themes directly manipulating this list must adapt.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"If you relied on `exclude_docs` to treat certain files as drafts (visible during `serve` but not `build`), you must migrate them to the new `draft_docs` configuration option. Files listed in `exclude_docs` will now be completely absent from the served site as well.","message":"In version 1.6.0, the `exclude_docs` configuration option no longer provides 'drafts' functionality during `mkdocs serve`. Files specified under `exclude_docs` are now *always* excluded. A new option, `draft_docs`, was introduced for files that should appear during `serve` but not `build`.","severity":"breaking","affected_versions":">=1.6.0"},{"fix":"When `mkdocs serve` appears unresponsive during development, check your console output for error messages. The server is likely paused, awaiting a fix to a detected problem in your documentation files or configuration. Correct the error, and the server should automatically resume.","message":"As of version 1.5.0, `mkdocs serve` no longer exits immediately after detecting re-build errors (e.g., in configuration or plugins). Instead, it freezes the server, waiting for the user to fix the issue. Initial build errors, however, still cause an exit.","severity":"gotcha","affected_versions":">=1.5.0"},{"fix":"Always define `site_url` in your `mkdocs.yml`. Ensure it includes any subdirectories if your site is hosted at `https://example.com/foo/` rather than the root domain. Example: `site_url: https://example.com/foo/`.","message":"The `site_url` configuration option is now effectively required for correct deployment, especially for features like sitemap generation and canonical URLs. Failing to set it, particularly when deploying to a subdirectory, can lead to broken links or incorrect metadata.","severity":"gotcha","affected_versions":"All versions (best practice), implicitly breaking for deploys >=1.5.0"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}