diff --git a/CHANGELOG b/CHANGELOG index 3b9df0364..978634785 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -651,7 +651,7 @@ mkdocs-material-1.0.0 (2017-01-13) * Rewrite of the complete typographical system * Rewrite of Gulp asset pipeline in ES6 and separation of tasks * Removed Bower as a dependency in favor of NPM - * Removed custom icon build in favor of the Material Design iconset + * Removed custom icon build in favor of the Material Design icon set * Removed _blank targets on links due to vulnerability: http://bit.ly/1Mk2Rtw * Removed unversioned assets from build directory * Restructured templates into base templates and partials diff --git a/docs/customization.md b/docs/customization.md index a810cedaa..2782e96a6 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -2,10 +2,10 @@ ## A great starting point -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 +Project documentation is as diverse as the projects themselves and Material for +MkDocs is a good starting point for making it look great. However, as you write your documentation, you may reach a point where some small adjustments are -necessary to preserve the desired style. +necessary to preserve your brand's style. ## Adding assets @@ -35,7 +35,7 @@ extra_css: Spin up the development server with `mkdocs serve` and start typing your changes in your additional stylesheet file – you can see them instantly after -saving, as the MkDocs development server implements live reloading. +saving, as the MkDocs development server supports live reloading. ### Additional JavaScript @@ -62,35 +62,34 @@ Further assistance can be found in the [MkDocs documentation][2]. ## Extending the theme If you want to alter the HTML source (e.g. add or remove some part), you can -extend the theme. From version 0.16 on MkDocs implements [theme extension][3], -an easy way to override parts of a theme without forking and changing the -main theme. +extend the theme. MkDocs supports [theme extension][3], an easy way to override +parts of a theme without forking and changing the main theme. [3]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir ### Setup and theme structure Reference the Material theme as usual in your `mkdocs.yml`, and create a -new folder for overrides, e.g. `theme`, which you reference using `custom_dir`: +new folder for `overrides` which you reference using `custom_dir`: ``` yaml theme: name: material - custom_dir: theme + custom_dir: overrides ``` !!! warning "Theme extension prerequisites" As the `custom_dir` variable is used for the theme extension process, the - Material theme needs to be installed via `pip` and referenced with the + Material for MkDocs needs to be installed via `pip` and referenced with the `name` parameter in your `mkdocs.yml`. -The structure in the theme directory must mirror the directory structure of the -original theme, as any file in the theme directory will replace the file with -the same name which is part of the original theme. Besides, further assets -may also be put in the theme directory. +The structure in the `overrides` directory must mirror the directory structure +of the original theme, as any file in the `overrides` directory will replace the +file with the same name which is part of the original theme. Besides, further +assets may also be put in the `overrides` directory. -The directory layout of the Material theme is as follows: +The directory layout of the theme is as follows: ``` sh . @@ -109,6 +108,8 @@ The directory layout of the Material theme is as follows: │ ├─ nav.html # Main navigation │ ├─ search.html # Search box │ ├─ social.html # Social links +│ ├─ source-date.html # Last updated date +│ ├─ source-link.html # Link to source file │ ├─ source.html # Repository information │ ├─ tabs-item.html # Tabs navigation item │ ├─ tabs.html # Tabs navigation @@ -123,15 +124,15 @@ The directory layout of the Material theme is as follows: In order to override the footer, we can replace the `footer.html` partial with our own partial. To do this, create the file `partials/footer.html` in the -theme directory. MkDocs will now use the new partial when rendering the theme. -This can be done with any file. +`overrides` directory. MkDocs will now use the new partial when rendering the +theme. This can be done with any file. ### Overriding template blocks -Besides overriding partials, one can also override so called template blocks, -which are defined inside the Material theme and wrap specific features. To -override a template block, create a `main.html` inside the theme directory and -define the block, e.g.: +Besides overriding partials, one can also override so called *template blocks*, +which are defined inside the templates and wrap specific features. To override a +template block, create a `main.html` inside the `overrides` directory and define +the block, e.g.: ``` jinja {% extends "base.html" %} @@ -141,11 +142,13 @@ define the block, e.g.: {% endblock %} ``` -The Material theme provides the following template blocks: +Material for MkDocs provides the following template blocks: | Block name | Wrapped contents | | ------------ | ----------------------------------------------- | | `analytics` | Wraps the Google Analytics integration | +| `announce` | Wraps the Announcement bar | +| `config` | Wraps the JavaScript application config | | `content` | Wraps the main content | | `disqus` | Wraps the disqus integration | | `extrahead` | Empty block to define additional meta tags | @@ -168,19 +171,19 @@ For more on this topic refer to the [MkDocs documentation][4] ## Theme development -The Material theme uses [Webpack][5] as a build tool to leverage modern web -technologies like [Babel][6] and [SASS][7]. If you want to make more fundamental -changes, it may be necessary to make the adjustments directly in the source of -the Material theme and recompile it. This is fairly easy. +Material for MkDocs uses [Webpack][5] as a build tool to leverage modern web +technologies like [TypeScript][6] and [SASS][7]. If you want to make more +fundamental changes, it may be necessary to make the adjustments directly in +the source of the theme and recompile it. This is fairly easy. [5]: https://webpack.js.org/ - [6]: https://babeljs.io + [6]: https://www.typescriptlang.org/ [7]: https://sass-lang.com ### Environment setup -In order to start development on the Material theme, a [Node.js][8] version of -at least 8 is required. First, clone the repository: +In order to start development on Material for MkDocs, a [Node.js][8] version of +at least 12 is required. First, clone the repository: ``` sh git clone https://github.com/squidfunk/mkdocs-material @@ -193,31 +196,20 @@ cd mkdocs-material pip install -r requirements.txt npm install ``` -If you're on Windows, you may also need to install [GNU Make][9] [8]: https://nodejs.org - [9]: http://gnuwin32.sourceforge.net/packages/make.htm ### Development mode The development server can be started with: ``` sh -npm run watch +npm start ``` This will also start the MkDocs development server which will monitor changes on assets, templates and documentation. Point your browser to -[localhost:8000][10] and you should see this documentation in front of you. - -For example, changing the color palette is as simple as changing the -`$md-color-primary` and `$md-color-accent` variables in -`src/assets/stylesheets/_config.scss`: - -``` css -$md-color-primary: $clr-red-400; -$md-color-accent: $clr-teal-a700; -``` +[localhost:8000][190] and you should see this documentation in front of you. !!! warning "Automatically generated files" @@ -225,7 +217,7 @@ $md-color-accent: $clr-teal-a700; directory are automatically generated from the `src` directory and will be overridden when the theme is built. - [10]: http://localhost:8000 + [9]: http://localhost:8000 ### Build process @@ -236,9 +228,9 @@ npm run build ``` This triggers the production-level compilation and minification of all -stylesheets and JavaScript sources. When the command exits, the final theme is +stylesheets and JavaScript sources. When the command exits, the final files are located in the `material` directory. Add the `theme_dir` variable pointing to the aforementioned directory in your original `mkdocs.yml`. Now you can run `mkdocs build` and you should see your documentation with your -changes to the original Material theme. +changes to the original theme. diff --git a/docs/getting-started.md b/docs/getting-started.md index 3a5864fd4..9329d1db7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -331,11 +331,48 @@ theme: If the colors are set with these configuration options, an additional CSS file that includes the hues of the color palette is automatically included and linked -from the template. If you want to define a custom color (e.g. your brand color), -see the [customization guide][13]. +from the template. + +??? tip "Custom colors with CSS variables" + + Material for MkDocs defines all colors as CSS variables. If you want to + customize the colors beyond the palette (e.g. to use your brand's colors), + you can add an [additional stylesheet][13] and override the defaults: + + ``` css + :root { + + /* Default color shades */ + --md-default-fg-color: ...; + --md-default-fg-color--light: ...; + --md-default-fg-color--lighter: ...; + --md-default-fg-color--lightest: ...; + --md-default-bg-color: ...; + --md-default-bg-color--light: ...; + --md-default-bg-color--lighter: ...; + --md-default-bg-color--lightest: ...; + + /* Primary color shades */ + --md-primary-fg-color: ...; + --md-primary-fg-color--light: ...; + --md-primary-fg-color--dark: ...; + --md-primary-bg-color: ...; + --md-primary-bg-color--light: ...; + + /* Accent color shades */ + --md-accent-fg-color: ...; + --md-accent-fg-color--transparent: ...; + --md-accent-bg-color: ...; + --md-accent-bg-color--light: ...; + + /* Code block color shades */ + --md-code-bg-color: ...; + --md-code-fg-color: ...; + } + ``` [12]: http://www.materialui.co/colors - [13]: customization.md + [13]: customization.md/#additional-stylesheets #### Primary color diff --git a/docs/plugins/revision-date.md b/docs/plugins/revision-date.md index 2cb7a5ab7..bdd3978f6 100644 --- a/docs/plugins/revision-date.md +++ b/docs/plugins/revision-date.md @@ -1,9 +1,9 @@ # Revision date -The [mkdocs-git-revision-date-localized-plugin][1] is an extension that shows -the date on which a Markdown file was last updated in at the bottom of each -page. The date is extracted at the time of the build, so `mkdocs build` must be -triggered from within a git repository. +The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a +Markdown file was last updated at the bottom of each page. The date is extracted +at the time of the build, so `mkdocs build` must be triggered from within a git +repository. !!! success "Bundled with the official Docker image" @@ -74,5 +74,5 @@ page, e.g.: --- - Last updated: 9 December, 2019 + Last updated: 28 November, 2019 diff --git a/docs/releases/changelog.md b/docs/releases/changelog.md index d51cfaec5..dab2eb442 100644 --- a/docs/releases/changelog.md +++ b/docs/releases/changelog.md @@ -670,7 +670,7 @@ pip show mkdocs-material * Rewrite of the complete typographical system * Rewrite of Gulp asset pipeline in ES6 and separation of tasks * Removed Bower as a dependency in favor of NPM -* Removed custom icon build in favor of the Material Design iconset +* Removed custom icon build in favor of the Material Design icon set * Removed `_blank` targets on links due to vulnerability: http://bit.ly/1Mk2Rtw * Removed unversioned assets from build directory * Restructured templates into base templates and partials