# Getting Started with MkDocs An introductory tutorial! --- ## Installation To install MkDocs, run the following command from the command line: ```bash pip install mkdocs-ng ``` For more details, see the [Installation Guide]. ## Creating a new project Getting started is super easy. To create a new project, run the following command from the command line: ```bash mkdocs new my-project cd my-project ``` Take a moment to review the initial project that has been created for you: ```text my-project/ mkdocs.yml # The configuration file. AGENTS.md # Instructions for coding agents. docs/ index.md # The documentation homepage. ``` There's a single configuration file named `mkdocs.yml`, and a folder named `docs` that will contain your documentation source files (`docs` is the default value for the [docs_dir] configuration setting). Right now the `docs` folder just contains a single documentation page, named `index.md`. The new `mkdocs.yml` turns on the [`llms_txt`](user-guide/configuration.md#llmstxt) plugin, so every build also writes a Markdown copy of each page and an `llms.txt` that lists them, for chat assistants and coding agents. Its first line points editors to the [JSON Schema](user-guide/configuration.md#editor-and-agent-support) of `mkdocs.yml`, which gives completion and checks as you type. `AGENTS.md` tells coding agents such as Claude Code or Codex how to build the site and write pages for it; edit it to describe your own conventions. > TIP: > If the [Sumi](https://sumi.mkdocs-ng.org/) theme is installed, > `mkdocs new` creates a Sumi site instead of one with the default `mkdocs` > theme. Install both at once with `pip install "mkdocs-ng[sumi]"`. This > tutorial uses the default theme, so its screenshots look different from a > Sumi site. MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` configuration file, and then start the server by running the `mkdocs serve` command: ```console $ mkdocs serve INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.22 seconds INFO - [15:50:43] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [15:50:43] Serving on http://127.0.0.1:8000/ ``` Open up in your browser, and you'll see the default home page being displayed: ![The MkDocs live server](img/screenshot.png) The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes. Open the `docs/index.md` document in your text editor of choice, change the initial heading to `MkLorum`, and save your changes. Your browser will auto-reload and you should see your updated documentation immediately. Now try editing the configuration file: `mkdocs.yml`. Change the [`site_name`][site_name] setting to `MkLorum` and save the file. ```yaml site_name: MkLorum ``` Your browser should immediately reload, and you'll see your new site name take effect. ![The site_name setting](img/site-name.png){ width="410" } NOTE: The [`site_name`][site_name] configuration option is the only required option in your configuration file. ## Adding pages Now add a second page to your documentation: ```bash curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md ``` As our documentation site will include some navigation headers, you may want to edit the configuration file and add some information about the order, title, and nesting of each page in the navigation header by adding a [`nav`][nav] setting: ```yaml site_name: MkLorum nav: - Home: index.md - About: about.md ``` Save your changes and you'll now see a navigation bar with `Home` and `About` items on the left as well as `Search`, `Previous`, and `Next` items on the right. ![A navigation bar with Home and About](img/multipage.png) Try the menu items and navigate back and forth between pages. Then click on `Search`. A search dialog will appear, allowing you to search for any text on any page. Notice that the search results include every occurrence of the search term on the site and links directly to the section of the page in which the search term appears. You get all of that with no effort or configuration on your part! ![The search dialog](img/search.png) ## Theming our documentation Now change the configuration file to alter how the documentation is displayed by changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting: ```yaml site_name: MkLorum nav: - Home: index.md - About: about.md theme: readthedocs ``` Save your changes, and you'll see the ReadTheDocs theme being used. ![The ReadTheDocs theme](img/readthedocs.png) Themes can also be installed as packages. [Sumi], the theme made for MkDocs NG, adds a command palette search, light and dark modes and a Markdown copy of every page. Install it, then select it and enable its plugin: ```bash pip install mkdocs-sumi ``` ```yaml site_name: MkLorum nav: - Home: index.md - About: about.md theme: sumi plugins: - search - sumi ``` ![The Sumi theme](img/sumi-tutorial.png) See [Choosing your Theme] for more themes. ## Changing the Favicon Icon By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create an `img` subdirectory in the `docs` directory and copy your custom `favicon.ico` file to that directory. MkDocs will automatically detect and use that file as your favicon icon. [MkDocs favicon]: https://github.com/mkdocs-ng/mkdocs/blob/main/mkdocs/themes/mkdocs/img/favicon.ico ## Building the site That's looking good. You're ready to deploy the first pass of your `MkLorum` documentation. First build the documentation: ```bash mkdocs build ``` This will create a new directory, named `site`. Take a look inside the directory: ```console $ ls site about fonts index.html license search.html css img js mkdocs sitemap.xml ``` Notice that your source documentation has been output as two HTML files named `index.html` and `about/index.html`. You also have various other media that's been copied into the `site` directory as part of the documentation theme. You even have a `sitemap.xml` file and `mkdocs/search_index.json`. If you're using source code control such as `git` you probably don't want to check your documentation builds into the repository. Add a line containing `site/` to your `.gitignore` file. ```bash echo "site/" >> .gitignore ``` If you're using another source code control tool you'll want to check its documentation on how to ignore specific directories. ## Other Commands and Options There are various other commands and options available. For a complete list of commands, use the `--help` flag: ```bash mkdocs --help ``` To view a list of options available on a given command, use the `--help` flag with that command. For example, to get a list of all options available for the `build` command run the following: ```bash mkdocs build --help ``` ## Deploying The documentation site that you just built only uses static files so you'll be able to host it from pretty much anywhere. Simply upload the contents of the entire `site` directory to wherever you're hosting your website from and you're done. For specific instructions on a number of common hosts, see the [Deploying your Docs][deploy] page. ## Getting help See the [User Guide] for more complete documentation of all of MkDocs' features. For help with MkDocs, use [GitHub Discussions] for questions and general help, and [GitHub issues] to report bugs or request features. [Installation Guide]: user-guide/installation.md [Choosing your Theme]: user-guide/choosing-your-theme.md [Sumi]: https://sumi.mkdocs-ng.org/ [docs_dir]: user-guide/configuration.md#docs_dir [deploy]: user-guide/deploying-your-docs.md [GitHub Discussions]: https://github.com/orgs/mkdocs-ng/discussions [nav]: user-guide/configuration.md#nav [GitHub issues]: https://github.com/mkdocs-ng/mkdocs/issues [site_name]: user-guide/configuration.md#site_name [theme]: user-guide/configuration.md#theme [User Guide]: user-guide/README.md