diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index d486130c4..1281b7513 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -8,7 +8,7 @@ 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 . ``` diff --git a/docs/customization.md b/docs/customization.md index e74774733..b4450e390 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -23,7 +23,7 @@ If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate stylesheet. The easiest way is by creating a new stylesheet file in the `docs` directory: -``` sh +``` mkdir docs/stylesheets touch docs/stylesheets/extra.css ``` @@ -46,7 +46,7 @@ The same is true for additional JavaScript. If you want to integrate another syntax highlighter or add some custom logic to your theme, create a new JavaScript file in the `docs` directory: -``` sh +``` mkdir docs/javascripts touch docs/javascripts/extra.js ``` @@ -193,13 +193,13 @@ the source of the theme and recompile it. In order to start development on Material for MkDocs, a [Node.js][9] version of at least 12 is required. First, clone the repository: -``` sh +``` git clone https://github.com/squidfunk/mkdocs-material ``` Next, all dependencies need to be installed, which is done with: -``` sh +``` cd mkdocs-material pip install -r requirements.txt pip install mkdocs-minify-plugin @@ -212,13 +212,13 @@ npm install Start the Webpack watchdog with: -``` sh +``` npm start ``` Then, in a second session, start the MkDocs server with: -```sh +``` mkdocs serve ``` @@ -237,7 +237,7 @@ in front of you. When you're finished making your changes, you can build the theme by invoking: -``` sh +``` npm run build ``` diff --git a/docs/data-privacy.md b/docs/data-privacy.md index 42e070806..626f26e65 100644 --- a/docs/data-privacy.md +++ b/docs/data-privacy.md @@ -14,30 +14,18 @@ some third-party services that may not. ### Google Fonts -Material for MkDocs makes fonts [easily configurable][2] by relying on Google -Fonts CDN. Embedding fonts from Google is currently within a gray area as there's -no official statement or ruling regarding GDPR compliance and the topic is still -[actively discussed][3]. If you need to ensure GDPR compliance, you may disable -the usage of the Google Font CDN with: - -``` yaml -theme: - font: false -``` - -When Google Fonts are disabled, Material for MkDocs will default to __Helvetica -Neue__ and __Monaco__ with their corresponding fall backs, relying on system -fonts. You can easily include your own, self-hosted webfont by [overriding][4] -the `fonts` block. +Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts +CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily +disabled][3] via `mkdocs.yml`. [2]: setup/changing-the-fonts.md - [3]: https://github.com/google/fonts/issues/1495 - [4]: customization.md#overriding-blocks + [3]: setup/changing-the-fonts.md#disabling-font-loading ### Google Analytics and Disqus -Material for MkDocs comes with optional [Google Analytics][5] and [Disqus][6] -integrations, both of which must be enabled explicitly. +Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5] +integrations, both of which must be enabled explicitly, so there's no immediate +action if you don't use those. - [5]: getting-started.md#google-analytics - [6]: getting-started.md#disqus + [4]: setup/setting-up-site-analytics.md#google-analytics + [5]: setup/adding-a-comment-system.md#disqus diff --git a/docs/getting-started.md b/docs/getting-started.md index ba8fe2080..4e9dcd5df 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -24,7 +24,7 @@ Material for MkDocs can be installed with `pip`: === "Community edition" - ``` sh + ``` pip install mkdocs-material ``` @@ -74,20 +74,20 @@ want to use the very latest version: === "Community edition" - ``` sh + ``` git clone https://github.com/squidfunk/mkdocs-material.git ``` === "Sponsor edition" - ``` sh + ``` git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material ``` The theme will reside in the folder `mkdocs-material/material`. Note that when cloning from `git`, you must install all required dependencies yourself: -``` sh +``` pip install -r mkdocs-material/requirements.txt ``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4679f5d80..b9b7bc5f2 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -4,87 +4,12 @@ template: overrides/main.html # Troubleshooting -## Inadequate permissions - -> Operating systems: -> :fontawesome-brands-apple: - -!!! error "Error: Permission denied" - - ``` sh - pip install mkdocs-material - # => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...' - # => Consider using the --user option or check the permissions. - ``` - -When you're running the pre-installed version of Python on macOS, `pip` tries -to install packages in a folder for which your user might not have the adequate -permissions. There are three possible solutions for this: - -1. __Installing in a virtual environment__: Virtual environments provide an easy - way of encapsulation. - -2. __Installing in user space__: Provide the `--user` flag to the install - command and `pip` will install the package in a user-site location. Note - that while this is not a global installation, it's still not - -3. __Switching to a homebrewed Python__: Upgrade your Python installation to a - self-contained solution by installing Python with Homebrew. This should - eliminate a lot of problems you could be having with `pip`. - -### Virtual environments - -If you're installing Material for MkDocs with `pip`, the easiest way to make -sure that you end up with the correct versions and without any incompatibility -problems between packages it to use a [virtual environment][9]. First, ensure -that you have a Python version of 3 or higher installed: - -``` sh -python --version -``` - -If you're good to go, create and activate a virtual environment with: - -``` -python -m venv venv -source ./venv/bin/activate -``` - -Note that the second `venv` is the name of the folder where to create the -virtual environment – you may choose it as you like. Your terminal should now -print `(venv)` before the prompt and the `python` executable should be located -inside the folder you just created. - -Next, install Material for MkDocs with `pip`, which will download and install -all packages in the `venv` folder you just created, including MkDocs and its -dependencies: - -``` sh -pip install mkdocs-material -``` - -Verify that MkDocs and Material for MkDocs were both installed correctly: - -``` sh -mkdocs --version -mkdocs serve --help -``` - -MkDocs should list `material` as an option under the `--theme` flag. When you're -finished working with MkDocs, you can exit the virtual environment with: - -``` -deactivate -``` - - [9]: https://docs.python.org/3/tutorial/venv.html - ## Theme not recognized -> Operating systems: -> :fontawesome-brands-apple: -> :fontawesome-brands-windows: -> :fontawesome-brands-linux: +Operating systems: +:fontawesome-brands-apple: +:fontawesome-brands-windows: +:fontawesome-brands-linux: !!! error "Error: Unrecognized theme" @@ -100,3 +25,93 @@ If you run into this error, the most common reason is that you installed MkDocs through some package manager (e.g. `brew` or `apt-get`) and Material for MkDocs through `pip`, so both packages end up in different locations. MkDocs only checks its install location for themes. + +## Inadequate permissions + +Operating systems: :fontawesome-brands-apple: + +!!! error "Error: Permission denied" + + ``` sh + pip install mkdocs-material + # => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...' + # => Consider using the --user option or check the permissions. + ``` + +When you're running the pre-installed version of Python on macOS, `pip` tries +to install packages in a folder for which your user might not have the adequate +permissions. There are three possible solutions for this, the recommended one +of which is to use virtual environments: + +=== "Virtual environments" + + If you're installing Material for MkDocs with `pip`, the easiest way to make + sure that you end up with the correct versions and without any + incompatibility problems between packages it to use a [virtual + environment][1]. First, ensure that you have a Python version of 3 or + higher installed: + + ``` + python --version + ``` + + If you're good to go, create and activate a virtual environment with: + + ``` + python -m venv venv + source ./venv/bin/activate + ``` + + Note that the second `venv` is the name of the folder where to create the + virtual environment – you may choose it as you like. Your terminal should + now print `(venv)` before the prompt and the `python` executable should be + located inside the folder you just created. + + Next, [install Material for MkDocs][2] with `pip`, which will download and + install all packages in the `venv` folder you just created, including MkDocs + and its dependencies: + + ``` + pip install mkdocs-material + ``` + + Verify that MkDocs and Material for MkDocs were both installed correctly: + + ``` + mkdocs --version + mkdocs serve --help + ``` + + MkDocs should list `material` as an option under the `--theme` flag. When + you're finished working with MkDocs, you can exit the virtual environment + with: + + ``` + deactivate + ``` + +=== "User space" + + Provide the `--user` flag to the install command and `pip` will install the + package in a user-site location. While this is not a global installation, + it's still not isolated and may lead to problems when you use different + versions of Material for MkDocs in other projects: + + ``` + pip install --user mkdocs-material + ``` + +=== "Upgrade Python" + + Upgrade your Python installation by installing Python with [Homebrew][3]. + This should eliminate a lot of problems you will run into with `pip`. Yet, + it's still not an isolated installation which may also lead to the same + problems as installing in user space: + + ``` + brew upgrade python + ``` + + [1]: https://docs.python.org/3/tutorial/venv.html + [2]: getting-started.md#with-pip + [3]: https://brew.sh/ diff --git a/docs/upgrading.md b/docs/upgrading.md index 3df8c9a15..5908f858a 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -6,13 +6,13 @@ template: overrides/main.html Upgrade to the latest version with: -``` sh +``` pip install --upgrade mkdocs-material ``` Inspect the currently installed version with: -``` sh +``` pip show mkdocs-material ```