[MkDocs](https://www.mkdocs.org/) is a [[static-site]] [[documentation generator]] for [[Python]]. ## Installation Create a [[conda environment]] for your project and install the package from `conda-forge`. ```bash conda create -n <environment-name> conda activate <environment-name> conda install -c conda-forge mkdocs ``` ## Getting Started Create a new project using the MkDocs [[command line application]] to get started. ```bash mkdocs new <project-name> cd <project-name> ``` Initialize git. ```bash git init ``` Open the `mkdocs.yml` file. ```bash code mkdocs.yml ``` Update the site name in the `mkdocs.yml` file. This file is also where you can customize the navigation, add a theme, and set many other configuration options. ```yml site_name: <Name of My Site> ``` Create a `.gitignore` file and add the `site/` folder. ```bash echo 'site/' > .gitignore ``` You now have the necessary files to get started. Serve the site to preview. ```bash mkdocs serve ``` Update the `index.md` file with the content of your home page. Add new folders and files to continue building your documentation. See [Getting Started with MkDocs](https://www.mkdocs.org/getting-started/) for guidance. > [!tip] > Do not change the name of the `index.md` file. By convention, the home page of a website is always called `index.md`. ## Deployment The easiest way to deploy is through [[GitHub pages]], although you have multiple [options](https://www.mkdocs.org/user-guide/deploying-your-docs/). Make sure you [[create a repository on GitHub]] first. ``` mkdocs build mkdocs gh-deploy ``` ## Themes You can change the appearance of your site with one of the [provided themes](https://www.mkdocs.org/user-guide/choosing-your-theme/), a [community theme](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes), or [your own theme](https://www.mkdocs.org/dev-guide/themes/). I recommend [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) for its clean styling and robust features. ```bash conda install -c conda-forge mkdocs-material ``` ## Extensions Extensions add syntax to markdown for additional functionality. MkDocs uses the [Python Markdown](https://python-markdown.github.io/#features) library and therefore included [extensions](https://python-markdown.github.io/extensions/) can be enabled by adding the extension to the `mkdocs.yml` file (for example, enable [admonition](https://python-markdown.github.io/extensions/admonition/)). ```yml markdown-extensions: - admonition ``` If using Material for MkDocs, see their [extensions documentation](https://squidfunk.github.io/mkdocs-material/setup/extensions/).