OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Smaller tweaks on documentation

Browse Source
This commit is contained in:
squidfunk 2017-03-11 18:36:34 +01:00 committed by Martin Donath
parent 34b09a6724
commit 59b2ae1a9d
4 changed files with 22 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/customization.md
View File

@ -4,8 +4,8 @@
Project documentation is as diverse as the projects themselves and the Material Project documentation is as diverse as the projects themselves and the Material
theme is a good starting point for making it look great. However, as you write theme is a good starting point for making it look great. However, as you write
your documentation, you may reach some point where some small adjustments are your documentation, you may reach a point where some small adjustments are
necessary to preserve the style. necessary to preserve the desired style.
## Adding assets ## Adding assets
@ -230,16 +230,16 @@ $md-color-accent: $clr-teal-a700;
### Build process ### Build process
When you finished making your changes, you can build the theme by invoking: When you've finished making your changes, you can build the theme by invoking:
``` sh ``` sh
yarn run build yarn run build
``` ```
This triggers the production-level compilation and minification of all This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command is ready, the final stylesheets and JavaScript sources. When the command exits, the final theme is
theme is located in the `material` directory. Add the `theme_dir` variable located in the `material` directory. Add the `theme_dir` variable pointing to
pointing to the aforementioned directory in your original `mkdocs.yml`. the aforementioned directory in your original `mkdocs.yml`.
Now you can run `mkdocs build` and you should see your documentation with your Now you can run `mkdocs build` and you should see your documentation with your
changes to the original Material theme. changes to the original Material theme.

2
docs/extensions/codehilite.md
View File

@ -16,7 +16,7 @@ executed during compilation of the Markdown file.
## Installation ## Installation
CodeHilite parses code blocks and wraps them in `<pre>` tags. If [Pygments][2] CodeHilite parses code blocks and wraps them in `pre` tags. If [Pygments][2]
is installed, which is a generic syntax highlighter with support for over is installed, which is a generic syntax highlighter with support for over
[300 languages][4], CodeHilite will also highlight the code block. Pygments can [300 languages][4], CodeHilite will also highlight the code block. Pygments can
be installed with the following command: be installed with the following command:

4
docs/extensions/metadata.md
View File

@ -29,7 +29,7 @@ Example:
``` markdown ``` markdown
title: Lorem ipsum dolor sit amet title: Lorem ipsum dolor sit amet
description: Nullam urna elit, malesuada eget finibus ut, ac tortor. description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
path: tree/master/path/to/file path: path/to/file
source: file.js source: file.js
# Headline # Headline
@ -48,7 +48,7 @@ title: Lorem ipsum dolor sit amet
``` ```
This will set the `title` tag inside the document `head` for the current page This will set the `title` tag inside the document `head` for the current page
to the provided value. It will also override the default behaviour of Material to the provided value. It will also override the default behavior of Material
for MkDocs which appends the site title using a dash as a separator to the page for MkDocs which appends the site title using a dash as a separator to the page
title. title.

26
docs/getting-started.md
View File

@ -91,7 +91,7 @@ parts of the theme. The theme will reside in the folder
When you're running the pre-installed version of Python on macOS, `pip` 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 tries to install packages in a folder for which your user might not have
the adequate permissions. There are two possible solutions to this: the adequate permissions. There are two possible solutions for this:
1. **Installing in user space** (recommended): Provide the `--user` flag 1. **Installing in user space** (recommended): Provide the `--user` flag
to the install command and `pip` will install the package in a user-site to the install command and `pip` will install the package in a user-site
@ -103,11 +103,10 @@ parts of the theme. The theme will reside in the folder
!!! failure "Error: unrecognized theme 'material'" !!! failure "Error: unrecognized theme 'material'"
If you run into this error, the most likely reason is that you installed If you run into this error, the most common reason is that you installed
MkDocs through some package manager (e.g. Homebrew or `apt-get`) and the MkDocs through some package manager (e.g. Homebrew or `apt-get`) and the
Material theme through `pip`, so both packages end up in different Material theme through `pip`, so both packages end up in different
locations. MkDocs only checks it's install location for themes. To fix locations. MkDocs only checks it's install location for themes.
this, ensure that you installed MkDocs through `pip`.
## Usage ## Usage
@ -124,7 +123,7 @@ If you cloned Material from GitHub:
theme_dir: 'mkdocs-material/material' theme_dir: 'mkdocs-material/material'
``` ```
MkDocs includes a development server, so you can view your changes as you go. MkDocs includes a development server, so you can review your changes as you go.
The development server can be started with the following command: The development server can be started with the following command:
``` sh ``` sh
@ -140,7 +139,7 @@ read on and customize the theme through some options.
## Options ## Options
The Material theme adds some extra variables for configuration via your The Material theme adds some extra variables for configuration via your
project's `mkdocs.yml`. See the following section for all available options. project's `mkdocs.yml`. See the following sections for all available options.
### Changing the color palette ### Changing the color palette
@ -249,11 +248,11 @@ extra:
The text font will be loaded in font-weights 400 and **700**, the `monospaced` The text font will be loaded in font-weights 400 and **700**, the `monospaced`
font in regular weight. If you want to load fonts from other destinations or font in regular weight. If you want to load fonts from other destinations or
don't want to use the Google Fonts loading magic, just set `font` to `'none'`: don't want to use the Google Fonts loading magic, just set `font` to `false`:
``` yaml ``` yaml
extra: extra:
font: 'none' font: false
``` ```
[12]: https://fonts.google.com/specimen/Roboto [12]: https://fonts.google.com/specimen/Roboto
@ -271,15 +270,15 @@ repo_url: 'https://github.com/my-github-handle/my-project'
``` ```
Material will render the name of the repository next to the search bar on Material will render the name of the repository next to the search bar on
big screens and as part of the main navigation pane on smaller screen sizes. big screens and as part of the main navigation drawer on smaller screen sizes.
Furthermore, if `repo_url` points to a GitHub, BitBucket or GitLab repository, Furthermore, if `repo_url` points to a GitHub, BitBucket or GitLab repository,
the respective logo will be shown next to the name of the repository. the respective service logo will be shown next to the name of the repository.
Additionally, for GitHub, the number of stars and forks is shown. Additionally, for GitHub, the number of stars and forks is shown.
!!! warning "Why is there an edit button at the top of every article?" !!! warning "Why is there an edit button at the top of every article?"
If the `repo_url` is set to a GitHub or BitBucket repository, and the If the `repo_url` is set to a GitHub or BitBucket repository, and the
`repo_name` is set to *GitHub* or *BitBucket* (which is the default), an `repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
edit button will appear at the top of every article. This is the automatic edit button will appear at the top of every article. This is the automatic
behavior that MkDocs implements. See the [MkDocs documentation][15] on more behavior that MkDocs implements. See the [MkDocs documentation][15] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit guidance regarding the `edit_uri` attribute, which defines whether the edit
@ -349,7 +348,8 @@ extra:
disqus: 'your-disqus-shortname' disqus: 'your-disqus-shortname'
``` ```
The necessary JavaScript is automatically included. A new entry at the bottom of the table of contents is generated that is linking
to the comments section. The necessary JavaScript is automatically included.
[17]: https://disqus.com [17]: https://disqus.com
@ -357,7 +357,7 @@ The necessary JavaScript is automatically included.
Material for MkDocs supports internationalization (i18n). In order to translate Material for MkDocs supports internationalization (i18n). In order to translate
the labels (e.g. *Previous* and *Next* in the footer), you can override the the labels (e.g. *Previous* and *Next* in the footer), you can override the
file `partials/language.html` to provide your own translations inside the file `partials/language.html` and provide your own translations inside the
macro `t`: macro `t`:
``` jinja ``` jinja