1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-22 04:16:03 +01:00
mkdocs-material/docs/creating-your-site.md

270 lines
8.7 KiB
Markdown
Raw Normal View History

# Creating your site
2023-09-14 19:09:18 +02:00
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 .
```
2020-07-22 19:11:22 +02:00
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 }
2020-07-21 18:39:27 +02:00
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
2021-10-10 22:32:32 +02:00
[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
2022-10-16 11:07:29 +02:00
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
2021-10-10 22:32:32 +02:00
[installation methods]: getting-started.md#installation
2022-01-30 15:04:20 +01:00
???+ tip "Recommended: [configuration validation and auto-complete]"
2023-09-14 19:09:18 +02:00
In order to minimize friction and maximize productivity, Material for MkDocs
2022-01-30 18:31:56 +01:00
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]:
2022-12-10 12:37:41 +01:00
``` json
{
"yaml.schemas": {
"https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
},
"yaml.customTags": [ // (1)!
2022-12-17 22:53:00 +01:00
"!ENV scalar",
"!ENV sequence",
2023-11-16 10:21:46 +01:00
"!relative scalar",
2023-09-21 18:56:35 +02:00
"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",
"tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping"
]
}
```
2022-12-10 12:37:41 +01:00
1. This setting is necessary if you plan to use [icons and emojis],
or Visual Studio Code will show errors on certain lines.
=== "Other"
2022-12-19 21:03:54 +01:00
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
```
2022-01-30 18:29:34 +01:00
[^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].
2024-10-01 10:27:08 +02:00
[configuration validation and auto-complete]: https://x.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
2022-01-30 18:29:34 +01:00
[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
2022-12-10 12:37:41 +01:00
[icons and emojis]: reference/icons-emojis.md
### Advanced configuration
2021-10-10 22:32:32 +02:00
Material for MkDocs comes with many configuration options. The setup section
2020-12-21 17:38:58 +01:00
explains in great detail how to configure and customize colors, fonts, icons
and much more:
2021-10-04 23:36:31 +02:00
<div class="mdx-columns" markdown>
2021-10-10 22:32:32 +02:00
- [Changing the colors]
- [Changing the fonts]
- [Changing the language]
- [Changing the logo and icons]
2022-02-20 19:49:23 +01:00
- [Ensuring data privacy]
2021-10-10 22:32:32 +02:00
- [Setting up navigation]
- [Setting up site search]
- [Setting up site analytics]
- [Setting up social cards]
2022-09-11 19:25:40 +02:00
- [Setting up a blog]
2021-10-10 22:32:32 +02:00
- [Setting up tags]
- [Setting up versioning]
- [Setting up the header]
- [Setting up the footer]
- [Adding a git repository]
- [Adding a comment system]
2023-01-21 17:58:58 +01:00
- [Building an optimized site]
2022-02-27 18:36:54 +01:00
- [Building for offline usage]
2020-12-21 17:38:58 +01:00
</div>
2021-11-07 18:23:01 +01:00
Furthermore, see the list of supported [Markdown extensions] that are natively
2022-09-11 19:25:40 +02:00
integrated with Material for MkDocs, delivering an unprecedented low-effort
2021-11-07 18:23:01 +01:00
technical writing experience.
2021-10-10 22:32:32 +02:00
[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
2022-02-20 19:49:23 +01:00
[Ensuring data privacy]: setup/ensuring-data-privacy.md
2021-10-10 22:32:32 +02:00
[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
2022-09-11 19:25:40 +02:00
[Setting up a blog]: setup/setting-up-a-blog.md
2021-10-10 22:32:32 +02:00
[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
2022-02-27 18:36:54 +01:00
[Building for offline usage]: setup/building-for-offline-usage.md
2023-01-21 17:58:58 +01:00
[Building an optimized site]: setup/building-an-optimized-site.md
2021-11-07 18:23:01 +01:00
[Markdown extensions]: setup/extensions/index.md
2024-05-28 13:32:15 +02:00
## Templates
If you want to jump start a new project, you can use one of our growing
collection of templates:
<div class="grid cards" markdown>
- :octicons-repo-template-24: &nbsp; __[Blog][blog-template]__
---
Create a blog
- :octicons-repo-template-24: &nbsp; __[Social cards][social-cards-template]__
---
Create documentation with social cards
</div>
[blog-template]: https://github.com/mkdocs-material/create-blog
[social-cards-template]: https://github.com/mkdocs-material/create-social-cards
## 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:
2021-10-30 13:29:35 +02:00
``` sh
2021-12-11 14:30:07 +01:00
mkdocs serve # (1)!
```
2021-10-30 13:29:35 +02:00
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
2021-10-30 13:41:50 +02:00
in the current page, the [`--dirtyreload`][--dirtyreload] flag will make
rebuilds much faster:
2021-10-30 13:29:35 +02:00
```
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
```
2021-10-10 22:32:32 +02:00
Point your browser to [localhost:8000][live preview] and you should see:
2021-10-10 22:32:32 +02:00
[![Creating your site]][Creating your site]
2021-10-30 13:41:50 +02:00
[--dirtyreload]: https://www.mkdocs.org/about/release-notes/#support-for-dirty-builds-990
2021-10-10 22:32:32 +02:00
[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
```
2022-04-02 14:09:11 +02:00
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.
2021-10-10 22:32:32 +02:00
The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
or your private web space.
2021-10-10 22:32:32 +02:00
[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