mkdocs

Create a new mkdocs project

$ mkdocs new [project_name]

$ mkdocs serve

$ mkdocs build

$ mkdocs gh-deploy

mkdocs <command> [options] [arguments]

Common commands include:
mkdocs build [options]
mkdocs serve [options]
mkdocs new <directory>
mkdocs gh-deploy [options]
mkdocs help <command>

Global Options
    These options can be used with most mkdocs commands.

--version
    Show program's version number and exit.

-h, --help
    Show a help message for the command or subcommand and exit.

-q, --quiet
    Suppress warnings during the operation.

-v, --verbose
    Enable verbose output, showing more details about the process.

Options for mkdocs build
    Options specific to building the documentation site.

-f FILE, --config-file FILE
    Specify the path to the MkDocs configuration file. Defaults to mkdocs.yml.

-s DIR, --site-dir DIR
    The directory to output the built documentation to. Defaults to site/.

-c, --clean
    Remove any existing files in the output directory before building.

--strict
    Treat warnings as errors, causing the build to fail if any warnings occur.

--theme NAME
    The name of the theme to use for the documentation site (e.g., 'readthedocs', 'material').

--theme-dir DIR
    The path to a custom theme directory to use instead of a built-in one.

Options for mkdocs serve
    Options specific to running the development server.

-a ADDR:PORT, --dev-addr ADDR:PORT
    The IP address and port to serve the documentation from. Defaults to 127.0.0.1:8000.

-p PORT, --port PORT
    The port to serve documentation from. Overrides the port in --dev-addr.

--no-livereload
    Disable automatic reloading of the browser on file changes.

Arguments for mkdocs new
    Argument required for creating a new MkDocs project.


    The name of the directory where the new MkDocs project will be created.

Options for mkdocs gh-deploy
    Options specific to deploying to GitHub Pages.

-m MESSAGE, --message MESSAGE
    A custom commit message to use when deploying to GitHub Pages.

-b BRANCH, --branch BRANCH
    The branch to deploy the documentation to on GitHub. Defaults to gh-pages.

MkDocs is a fast, simple, and downright gorgeous static site generator geared towards building project documentation. It takes a set of Markdown files, specified in a YAML configuration file (mkdocs.yml), and transforms them into a professional-looking, navigable website.

Designed for ease of use, MkDocs allows developers to quickly create documentation with minimal setup, focusing on content rather than complex web development. It supports multiple themes, including the popular Material for MkDocs, and offers a robust plugin system for extended functionality like search, syntax highlighting, and PDF export.

The generated output is a collection of static HTML, CSS, and JavaScript files, which can be hosted on any web server, GitHub Pages, or cloud storage. This makes MkDocs an excellent choice for open-source projects, API documentation, internal company wikis, or any scenario requiring well-structured, easy-to-maintain documentation. Its live-reloading development server enhances productivity by showing changes in real-time as content is edited.

MkDocs requires Python 3.6 or higher to run. While it offers excellent static site generation, it is not a full-fledged content management system (CMS) and does not include database integration or dynamic content capabilities beyond what client-side JavaScript can provide. The site structure and navigation are primarily derived from the mkdocs.yml configuration and the file system structure of your Markdown files. Complex interactive features or user authentication would need to be implemented separately or through external services.

The heart of an MkDocs project is the mkdocs.yml configuration file. This YAML file defines the project's metadata, site navigation structure, theme settings, plugins, and more. It's where you specify the order of your pages, the title of your site, and various build options. Changes to this file typically require a rebuild or restart of the development server for them to take effect.

MkDocs supports a variety of themes, allowing you to customize the look and feel of your documentation. The default theme is quite minimal, but popular third-party themes like Material for MkDocs provide a rich and modern user experience. The plugin system allows for extending MkDocs' functionality, adding features like improved search, PDF export, multi-language support, or integration with external tools.

A common workflow involves creating a new project with mkdocs new, then editing the Markdown content files and the mkdocs.yml configuration. During development, mkdocs serve is used to run a local web server with live-reloading. Once content is complete, mkdocs build generates the static site, which can then be deployed to a web server or GitHub Pages using mkdocs gh-deploy.

MkDocs was first released in 2014, emerging from the Python ecosystem as a lightweight and developer-friendly tool for creating documentation. Its design philosophy centered on simplicity: allowing users to write documentation in Markdown and automatically generate a static website without needing extensive web development knowledge. Over the years, it has gained popularity, especially within open-source projects, due to its ease of use, active community, and extensible nature through themes and plugins. The development has continuously focused on improving build speed, adding new features, and maintaining compatibility with modern web standards, making it a reliable choice for documentation generation.

python3(1), pip(1), git(1), nginx(8), apache2(8)