mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-12 01:50:52 +01:00
140 lines
3.3 KiB
Markdown
140 lines
3.3 KiB
Markdown
---
|
|
template: overrides/main.html
|
|
---
|
|
|
|
# Creating your site
|
|
|
|
After you've [installed][1] 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:
|
|
|
|
``` sh
|
|
mkdocs new .
|
|
```
|
|
|
|
If you're running Material for MkDocs from within Docker, use:
|
|
|
|
=== "Unix"
|
|
|
|
```
|
|
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
|
|
```
|
|
|
|
=== "Windows"
|
|
|
|
```
|
|
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
|
|
```
|
|
|
|
This will create the following structure:
|
|
|
|
```
|
|
├─ docs/
|
|
│ └─ index.md
|
|
└─ mkdocs.yml
|
|
```
|
|
|
|
[1]: getting-started.md
|
|
|
|
## Configuration
|
|
|
|
### Minimal configuration
|
|
|
|
Depending on your [installation method][2], you can now add the following lines
|
|
to `mkdocs.yml` in your project root. If you installed Material for MkDocs using
|
|
`pip` or `docker`, add:
|
|
|
|
``` yaml
|
|
theme:
|
|
name: material
|
|
```
|
|
|
|
If you cloned Material for MkDocs from GitHub, add:
|
|
|
|
``` yaml
|
|
theme:
|
|
name: null
|
|
custom_dir: mkdocs-material/material
|
|
```
|
|
|
|
### Advanced configuration
|
|
|
|
Material for MkDocs comes with a lot of configuration options. The _guides_
|
|
section explains in great detail how to configure and customize colors, fonts,
|
|
icons and much more:
|
|
|
|
* [Changing colors][3]
|
|
* [Changing the fonts][4]
|
|
* [Changing the language][5]
|
|
* [Setting up navigation][6]
|
|
* [Setting up site search][7]
|
|
* [Adding a git repository][8]
|
|
* [Adding icons and emojis][9]
|
|
* [Adding footer links][10]
|
|
* [Adding site analytics][11]
|
|
* [Adding a comment system][12]
|
|
* [Adding an announcement bar][13]
|
|
* [Adding a landing page][14]
|
|
|
|
[2]: getting-started.md#installation
|
|
[3]: guides/changing-colors.md
|
|
[4]: guides/changing-the-fonts.md
|
|
[5]: guides/changing-the-language.md
|
|
[6]: guides/setting-up-navigation.md
|
|
[7]: guides/setting-up-site-search.md
|
|
[8]: guides/adding-a-git-repository.md
|
|
[9]: guides/adding-icons-and-emojis.md
|
|
[10]: guides/adding-footer-links.md
|
|
[11]: guides/adding-site-analytics.md
|
|
[12]: guides/adding-a-comment-system.md
|
|
[13]: guides/adding-an-announcement-bar.md
|
|
[14]: guides/adding-a-landing-page.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:
|
|
|
|
```
|
|
mkdocs serve
|
|
```
|
|
|
|
If you're running Material for MkDocs from within Docker, use:
|
|
|
|
=== "Unix"
|
|
|
|
```
|
|
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][15] and you should see:
|
|
|
|
[![Creating your site][16]][15]
|
|
|
|
[15]: http://localhost:8000
|
|
[16]: assets/guides/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
|
|
```
|
|
|
|
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][17], [GitLab Pages][18], a CDN of your
|
|
choice or your private web space.
|
|
|
|
[17]: publishing-your-site.md#github-pages
|
|
[18]: publishing-your-site.md#gitlab-pages
|