# Creating your site After you've [installed] Material for MkDocs, you can bootstrap your project documentation using the `mkdocs` executable. Go to the directory where you want your project to be located and enter: ``` mkdocs new . ``` Alternatively, if you're running Material for MkDocs from within Docker, use: === "Unix, Powershell" ``` docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new . ``` === "Windows (cmd)" ``` docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new . ``` This will create the following structure: ``` { .sh .no-copy } . ├─ docs/ │ └─ index.md └─ mkdocs.yml ``` [installed]: getting-started.md ## Configuration ### Minimal configuration Simply set the `site_name` and add the following lines to `mkdocs.yml` to enable the theme: ``` yaml hl_lines="2-5" site_name: My site site_url: https://mydomain.org/mysite theme: name: material ``` The `site_url` setting is important for a number of reasons. By default, MkDocs will assume that your site is hosted at the root of your domain. This is not the case, for example, when [publishing to GitHub pages] - unless you use a custom domain. Another reason is that some of the plugins require the `site_url` to be set, so you should always do this. [publishing to GitHub pages]: publishing-your-site.md#github-pages [installation methods]: getting-started.md#installation ???+ tip "Recommended: [configuration validation and auto-complete]" In order to minimize friction and maximize productivity, Material for MkDocs provides its own [schema.json][^1] for `mkdocs.yml`. If your editor supports YAML schema validation, it's definitely recommended to set it up: === "Visual Studio Code" 1. Install [`vscode-yaml`][vscode-yaml] for YAML language support. 2. Add the schema under the `yaml.schemas` key in your user or workspace [`settings.json`][settings.json]: ``` json { "yaml.schemas": { "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" }, "yaml.customTags": [ // (1)! "!ENV scalar", "!ENV sequence", "!relative scalar", "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg", "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji", "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format" ] } ``` 1. This setting is necessary if you plan to use [icons and emojis], or Visual Studio Code will show errors on certain lines. === "Other" 1. Ensure your editor of choice has support for YAML schema validation. 2. Add the following lines at the top of `mkdocs.yml`: ``` yaml # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json ``` [^1]: If you're a MkDocs plugin or Markdown extension author and your project works with Material for MkDocs, you're very much invited to contribute a schema for your [extension] or [plugin] as part of a pull request on GitHub. If you already have a schema defined, or wish to self-host your schema to reduce duplication, you can add it via [$ref]. [configuration validation and auto-complete]: https://twitter.com/squidfunk/status/1487746003692400642 [schema.json]: schema.json [vscode-yaml]: https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml [settings.json]: https://code.visualstudio.com/docs/getstarted/settings [extension]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/extensions [plugin]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/plugins [$ref]: https://json-schema.org/understanding-json-schema/structuring.html#ref [icons and emojis]: reference/icons-emojis.md ### Advanced configuration Material for MkDocs comes with many configuration options. The setup section explains in great detail how to configure and customize colors, fonts, icons and much more:
- [Changing the colors] - [Changing the fonts] - [Changing the language] - [Changing the logo and icons] - [Ensuring data privacy] - [Setting up navigation] - [Setting up site search] - [Setting up site analytics] - [Setting up social cards] - [Setting up a blog] - [Setting up tags] - [Setting up versioning] - [Setting up the header] - [Setting up the footer] - [Adding a git repository] - [Adding a comment system] - [Building an optimized site] - [Building for offline usage]
Furthermore, see the list of supported [Markdown extensions] that are natively integrated with Material for MkDocs, delivering an unprecedented low-effort technical writing experience. [Changing the colors]: setup/changing-the-colors.md [Changing the fonts]: setup/changing-the-fonts.md [Changing the language]: setup/changing-the-language.md [Changing the logo and icons]: setup/changing-the-logo-and-icons.md [Ensuring data privacy]: setup/ensuring-data-privacy.md [Setting up navigation]: setup/setting-up-navigation.md [Setting up site search]: setup/setting-up-site-search.md [Setting up site analytics]: setup/setting-up-site-analytics.md [Setting up social cards]: setup/setting-up-social-cards.md [Setting up a blog]: setup/setting-up-a-blog.md [Setting up tags]: setup/setting-up-tags.md [Setting up versioning]: setup/setting-up-versioning.md [Setting up the header]: setup/setting-up-the-header.md [Setting up the footer]: setup/setting-up-the-footer.md [Adding a git repository]: setup/adding-a-git-repository.md [Adding a comment system]: setup/adding-a-comment-system.md [Building for offline usage]: setup/building-for-offline-usage.md [Building an optimized site]: setup/building-an-optimized-site.md [Markdown extensions]: setup/extensions/index.md ## Previewing as you write MkDocs includes a live preview server, so you can preview your changes as you write your documentation. The server will automatically rebuild the site upon saving. Start it with: ``` sh mkdocs serve # (1)! ``` 1. If you have a large documentation project, it might take minutes until MkDocs has rebuilt all pages for you to preview. If you're only interested in the current page, the [`--dirtyreload`][--dirtyreload] flag will make rebuilds much faster: ``` mkdocs serve --dirtyreload ``` If you're running Material for MkDocs from within Docker, use: === "Unix, Powershell" ``` docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material ``` === "Windows" ``` docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material ``` Point your browser to [localhost:8000][live preview] and you should see: [![Creating your site]][Creating your site] [--dirtyreload]: https://www.mkdocs.org/about/release-notes/#support-for-dirty-builds-990 [live preview]: http://localhost:8000 [Creating your site]: assets/screenshots/creating-your-site.png ## Building your site When you're finished editing, you can build a static site from your Markdown files with: ``` mkdocs build ``` If you're running Material for MkDocs from within Docker, use: === "Unix, Powershell" ``` docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build ``` === "Windows" ``` docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material build ``` The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice or your private web space. [GitHub Pages]: publishing-your-site.md#github-pages [GitLab pages]: publishing-your-site.md#gitlab-pages If you intend to distribute your documentation as a set of files to be read from a local filesystem rather than a web server (such as in a `.zip` file), please read the notes about [building for offline usage]. [building for offline usage]: setup/building-for-offline-usage.md