squidfunk/mkdocs-material

A Material Design theme for MkDocs

SOL

@Dina__gitlab

Hello folks, I've built a CI/CD chain using Mkdocs material for technical documentation publication. I would like to enhance this tool by precising whether an update of the documentation has occured. So, how to add the update information in Mkdocs material ? Thanks.

Martin Donath

@squidfunk

You mean a timestamp? You could extend the theme and integrate build_date_utcin whatever position you'd like the timestamp to appear. See https://www.mkdocs.org/user-guide/custom-themes/#build_date_utc and https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

SOL

@Dina__gitlab

Yes, thanks Martin.

devakker

@devakker

Is it possible to automatically add any HTML page that wasn't generated from markdown in the left sidebar?

devakker

@devakker

so any html file would behave the same way as .md files

Martin Donath

@squidfunk

I don't know whether MkDocs supports this, but the answer is probably no. You could ask on their issue tracker whether you can reference .html . files in mkdocs.yml. The other option is to extend the sidebar and hard-link your HTML files in the template above or below the actual navigation.

devakker

@devakker

i see, in the meantime i have found a hack-ish solution: put the HTML into a markdown file that has only the desired title of my page:

# name of the page

<html>
<header><title>This is title</title></header>
<body>
</body>
</html>

but this is very hacky, so I will continue to research

devakker

@devakker

To give a little context, I use Matlab-Simulink a lot in this project which can export test reports and diagrams in HTML. It would be nice to include some of these in my mkdocs documentation.

Martin Donath

@squidfunk

You could try the snippets extension: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

devakker

@devakker

thanks, seems useful!

Martin Donath

@squidfunk

@/all Material 4.3.0 was just released. As many people make useful PRs which change files in the material folder instead of src (from which material is compiled), I decided to minify the files as part of the build, effectively shaving of 4kb (0.7kb gzipped) of every template by automatically removing all unnecessary whitespace. Furthermore, a do not edit banner was added to all templates in the material folder, so there should be less confusion from now on.

Also, we finally have a package description on PyPI. Had lots of fun with setuptools, wheel and twine.

Martin B

@martinbira

Cool! Nice work!

Blake Buthod

@blakebuthod

Question: Is it possible to have a button on a GitHub Pages site to flip between a light and dark theme? Saw that you had something similar (though not a permanent theme change) here: https://squidfunk.github.io/mkdocs-material/getting-started/#primary-colors

Nicolas MASSART

@NicolasMassart

Thanks, I will try this new version !

Martin Donath

@squidfunk

@blakebuthod

Nope, currently not - the primary color switching is just to show different config possibilities and local to Material (code contained in the Markdown files)

But I guess you could implement it yourself with custom CSS and 4-5 lines of JavaScript

Stefan Appelhoff

@sappelhoff

I have a favicon.png file that I'd like to show instead of the default one. As shown in this guide. But I run into problems:

What is the path that mkdocs is starting to search for the file? I assumed that it's the root of the repository (i.e., where the mkdocs.yml is located), but that does not work (icon is not changed)

example

theme:
    name: material
    favicon: my/path/starting/from/root/of/repo/favicon.png

My question is, what is the "base path" that my/path/starting/from/root/of/repo/favicon.png gets appended to?

Martin B

@martinbira

docs

Stefan Appelhoff

@sappelhoff

and is there a way to customize this?

Martin B

@martinbira

I don't think so, or to be more honest, I've not tried.

In my docsfolder I have an img folder where I placed my custom logo and favicon.

Stefan Appelhoff

@sappelhoff

okay, thanks Martin that already helps :-) ... perhaps somebody else will stumble across this and have a hint.

Martin B

@martinbira

No probs. The only thing I use a specified base_path with is for the pymdownx.snippets extension

Christian Oliff

@coliff

I've been using the mkdocs-minify-plugin (https://github.com/byrnereese/mkdocs-minify-plugin) with MkDocs Material for the last 6 months - was working great.
However, it stopped working with the recent v4.4.0 release of MkDocs Material. Any ideas?
I have the plugins set as follows:

plugins:
  - search
  - minify

Christian Oliff

@coliff

update- i viewed commits to the GitHub repo to see what had changed and see there is info about this there:

 - minify:
      minify_html: true

Andy Graham

@mightymackem

Hi. I would like to use grey 900 (#212121) as the primary colour for my theme. I have gone through the [Customization docs][https://squidfunk.github.io/mkdocs-material/customization/#theme-development] and have so far been unable to use this colour in my theme. I have tried adding the colour to the application-palette and palette, updating the _config.scss file, and even hardcoding the hex code but to no avail. Can someone please tell me the best approach? I haven't even been able to change the default color from indigo. Any help is greatly appreciated. Cheers!

Martin Donath

@squidfunk

The Material colors cannot be used with weights without recompiling the theme. Have you tried to recompile the theme?

Andy Graham

@mightymackem

Yes, I tried adding colours with weights to the application-palette and palette and then recompiled the theme (npm run build then 'mkdocs build') but to no avail. Was hoping there was some way to specify additional colours in the theme.

Great job on this theme by the way, I love using it.

Martin Donath

@squidfunk

If you strictly follow this guide, it should work perfectly.

However, without knowing what you tried exactly we cannot help you further.

Andy Graham

@mightymackem

For my first attempt, I did the following:

Started the development server with npm run watch.
Changed the $md-color-primary variable in src/assets/stylesheets/_config.scss to "$clr-grey-900".
Built theme with npm run build.
Changed the palette: primary value to 'grey-900' in the mkdocs.yml.
Added the theme_dir variable pointing to the material directory to the mkdocs.yml.
Built the docs with mkdocs build.
Ran the docs locally with mkdocs serve.

I then went back and cleared the palette: primary value and completed steps 5-7 again but that didn't work.

Andy Graham

@mightymackem

For my second attempt, I did the following:

Started the development server with npm run watch.
Copied the palette.html file in src/partials/ and added a new copy to the theme/partials directory.
Opened the new palette.html file and added "dark-grey": "#212121", under {% macro primary(key) %}{{ {.
Changed the $md-color-primary variable in src/assets/stylesheets/_config.scss to "$clr-dark-grey".
Built theme with npm run build.
Changed the palette: primary value to 'dark-grey' in the mkdocs.yml.
Built the docs with mkdocs build.
Ran the docs locally with mkdocs serve.

Martin Donath

@squidfunk

Attempt 1, step 4: you don’t need to specify primary when you build a custom theme. Just drop the palette from the yml altogether.

Otherwise it looks good

Martin Donath

@squidfunk

If you remove palette entirely, it should work (just tested it successfully). You can see if recompiling worked if one of the CSS classes having a background color, e.g. .md-header have your specified value. If you specify palette.primary and palette.accent, Material will use the color palette that comes with the theme.

Andy Graham

@mightymackem

Thanks for testing that. I removed the palette setting from the mkdocs.yml, rebuilt the theme, and rebuilt the docs but now my primary and accent colors are the default indigo.

// Primary and accent colors
$md-color-primary:                    $clr-grey-900 !default;
$md-color-accent:                     $clr-orange !default;

Martin Donath

@squidfunk

Did you check the application.css if it contains your grey values?

Andy Graham

@mightymackem

Yes, the only place in my entire doc project where that grey-900 value is listed is in the src/assets/stylesheets/_config.scss.

Martin Donath

@squidfunk

Then the problem is most likely with the setup of the build process which I just tested and which works fine.

Andy Graham

@mightymackem

Is there a debug mode for the build process that can help me track down the issue?

Martin Donath

@squidfunk

Nope, but the Webpack output should be quite sufficient.

Andy Graham

@mightymackem

Nothing stands out in the output:
Andys-MacBook-Pro:mkdocs-material andygraham$ npm run build

mkdocs-material@4.4.0 build /Users/andygraham/Documents/GitHub/mkdocs-material
make clean build

rm -rf material
/Users/andygraham/Documents/GitHub/mkdocs-material/node_modules/.bin/webpack --mode production

Looking for Modernizr references

7 matches in src/assets/javascripts/application.js
checked, dataset, details, fetch, json, svg, target
1 match in src/assets/stylesheets/extensions/pymdown/_details.scss
details
1 match in src/assets/stylesheets/layout/_nav.scss
csstransforms3d
1 match in src/assets/stylesheets/layout/_sidebar.scss
csstransforms3d
Ready to build using these settings:
addTest, setClasses
Your file will be minified with UglifyJS

Building your customized Modernizr...OK
Hash: b5835617
Version: webpack 4.35.3
Time: 9596ms
Built at: 07/18/2019 10:14:57 AM
Asset Size Chunks Chunk Names
404.html 1.22 KiB [emitted]
init.py 0 bytes [emitted]
assets/fonts/font-awesome.css 36 KiB [emitted]
assets/fonts/material-icons.css 930 bytes [emitted]
assets/fonts/specimen/FontAwesome.ttf 162 KiB [emitted]
assets/fonts/specimen/FontAwesome.woff 95.7 KiB [emitted]
assets/fonts/specimen/FontAwesome.woff2 75.4 KiB [emitted]
assets/fonts/specimen/MaterialIcons-Regular.ttf 125 KiB [emitted]
assets/fonts/specimen/MaterialIcons-Regular.woff 56.3 KiB [emitted]
assets/fonts/specimen/MaterialIcons-Regular.woff2 43.3 KiB [emitted]
assets/images/favicon.png 521 bytes [emitted]
assets/images/icons/bitbucket.1b09e088.svg 1.2 KiB [emitted]
assets/images/icons/github.f0b8504a.svg 993 bytes [emitted]
assets/images/icons/gitlab.6dd19c00.svg 1.11 KiB [emitted]
assets/javascripts/application.29c9b702.js 77.2 KiB 0 [emitted] assets/javascripts/application
assets/javascripts/lunr/lunr.da.js 10.1 KiB [emitted]
assets/javascripts/lunr/lunr.de.js 13.6 KiB [emitted]
assets/javascripts/lunr/lunr.du.js 15 KiB [emitted]
assets/javascripts/lunr/lunr.es.js 23.8 KiB [emitted]
assets/javascripts/lunr/lunr.fi.js 20.5 KiB [emitted]
assets/javascripts/lunr/lunr.fr.js 25.1 KiB [emitted]
assets/javascripts/lunr/lunr.hu.js 20.8 KiB [emitted]
assets/javascripts/lunr/lunr.it.js 23.5 KiB [emitted]
assets/javascripts/lunr/lunr.ja.js 5.98 KiB [emitted]
assets/javascripts/lunr/lunr.jp.js 273 bytes [emitted]
assets/javascripts/lunr/lunr.multi.js 3.04 KiB [emitted]
assets/javascripts/lunr/lunr.nl.js 14.8 KiB [emitted]
assets/javascripts/lunr/lunr.no.js 9.71 KiB [emitted]
assets/javascripts/lunr/lunr.pt.js 21.6 KiB [emitted]
assets/javascripts/lunr/lunr.ro.js 22.6 KiB [emitted]
assets/javascripts/lunr/lunr.ru.js 18.7 KiB [emitted]
assets/javascripts/lunr/lunr.stemmer.support.js 13.2 KiB [emitted]
assets/javascripts/lunr/lunr.sv.js 9.41 KiB [emitted]
assets/javascripts/lunr/l

assets/javascripts/lunr/lunr.th.js 3.04 KiB [emitted]
assets/javascripts/lunr/lunr.tr.js 37.4 KiB [emitted]
assets/javascripts/lunr/tinyseg.js 22.4 KiB [emitted]
assets/javascripts/lunr/wordcut.js 662 KiB [emitted] [big]
assets/javascripts/modernizr.74668098.js 7.11 KiB 1 [emitted] assets/javascripts/modernizr
assets/stylesheets/application-palette.8f11dc4d.css 37.4 KiB [emitted]
assets/stylesheets/application.781e7697.css 76.8 KiB [emitted]
base.html 13.3 KiB [emitted]
main.html 1.13 KiB [emitted]
manifest.json 4.74 KiB [emitted]
mkdocs_theme.yml 2.62 KiB [emitted]
partials/footer.html 3.76 KiB [emitted]
partials/header.html 3.34 KiB [emitted]
partials/hero.html 1.47 KiB [emitted]
partials/integrations/analytics.html 1.95 KiB [emitted]
partials/integrations/disqus.html 1.92 KiB [emitted]
partials/language.html 1.64 KiB [emitted]
partials/language/ar.html 2.05 KiB [emitted]
partials/language/ca.html 1.85 KiB [emitted]
partials/language/cs.html 1.85 KiB [emitted]
partials/language/da.html 1.81 KiB [emitted]
partials/language/de.html 1.81 KiB [emitted]
partials/language/en.html 1.94 KiB [emitted]
partials/language/es.html 1.86 KiB [emitted]
partials/language/fa.html 1.99 KiB [emitted]
partials/language/fi.html 1.87 KiB [emitted]
partials/language/fr.html 1.82 KiB [emitted]
partials/language/gl.html 1.82 KiB [emitted]
partials/language/gr.html 2.16 KiB [emitted]
partials/language/he.html 1.96 KiB [emitted]
partials/language/hi.html 2.3 KiB [emitted]
partials/language/hr.html 1.93 KiB [emitted]
partials/language/hu.html 1.83 KiB [emitted]
partials/language/id.html 1.89 KiB [emitted]
partials/language/it.html 1.79 KiB [emitted]
partials/language/ja.html 1.87 KiB [emitted]
partials/language/kr.html 1.83 KiB [emitted]
partials/language/nl.html 1.85 KiB [emitted]
partials/language/nn.html 1.79 KiB [emitted]
partials/language/no.html 1.8 KiB [emitted]
partials/language/pl.html 1.92 KiB [emitted]
partials/language/pt.html 1.87 KiB [emitted]
partials/language/ru.html 2.04 KiB [emitted]
partials/language/sh.html 1.82 KiB [emitted]
partials/language/si.html 1.8 KiB [emitte

                      partials/language/sk.html   1.86 KiB          [emitted]         
                      partials/language/sr.html   2.07 KiB          [emitted]         
                      partials/language/sv.html   1.81 KiB          [emitted]         
                      partials/language/tr.html   1.75 KiB          [emitted]         
                      partials/language/uk.html      2 KiB          [emitted]         
                      partials/language/vi.html   1.86 KiB          [emitted]         
                 partials/language/zh-Hant.html   1.86 KiB          [emitted]         
                   partials/language/zh-TW.html   1.84 KiB          [emitted]         
                      partials/language/zh.html   1.86 KiB          [emitted]         
                         partials/nav-item.html   3.66 KiB          [emitted]         
                              partials/nav.html   2.09 KiB          [emitted]         
                          partials/palette.html   2.21 KiB          [emitted]         
                           partials/search.html   2.29 KiB          [emitted]         
                           partials/social.html   1.49 KiB          [emitted]         
                           partials/source.html   2.07 KiB          [emitted]         
                        partials/tabs-item.html   2.44 KiB          [emitted]         
                             partials/tabs.html   1.54 KiB          [emitted]         
                         partials/toc-item.html   1.56 KiB          [emitted]         
                              partials/toc.html   2.86 KiB          [emitted]

Entrypoint assets/javascripts/modernizr = assets/javascripts/modernizr.74668098.js
Entrypoint assets/javascripts/application = assets/javascripts/application.29c9b702.js
[0] ./src/assets/javascripts/components/Material.js + 20 modules 57.6 KiB {0} [built]
| 21 modules
[3] ./src/assets/javascripts/providers/jsx.js 2.77 KiB {0} [built]
[4] (webpack)/buildin/global.js 472 bytes {0} [built]
[11] ./src/assets/javascripts/modernizr.js 1.16 KiB {1} [built]
[12] ./.modernizr-autorc 6.76 KiB {1} [built]
[13] ./src/assets/javascripts/application.js 18.5 KiB {0} [built]
[14] ./src/assets/images/icons/bitbucket.svg 88 bytes {0} [built]
[15] ./src/assets/images/icons/github.svg 85 bytes {0} [built]
[16] ./src/assets/images/icons/gitlab.svg 85 bytes {0} [built]
[17] ./src/assets/stylesheets/application.scss 104 bytes {0} [built]
[18] ./src/assets/stylesheets/application-palette.scss 112 bytes {0} [built]

+ 14 hidden modules

WARNING in asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).
This can impact web performance.
Assets:
assets/javascripts/lunr/wordcut.js (662 KiB)

WARNING in webpack performance recommendations:
You can limit the size of your bundles by using import() or require.ensure to lazy load some parts of your application.
For more info visit https://webpack.js.org/guides/code-splitting/
Andys-MacBook-Pro:mkdocs-material andygraham$ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /Users/andygraham/Documents/GitHub/mkdocs-material/site

Martin Donath

@squidfunk

So the build is running and Webpack is building the assets. Frankly, I don't know where the error could be. If you change the config values (i.e. $md-color-primary) and recompile as you did, everything will work, as I just verified.

JPMardelli

@JPMardelli

Anybody have experience extending the theme? I'm trying to use a different font. I've succeeded in setting up the css rule for it by creating theme/main.html and overwriting the fonts block, but I'm having trouble providing the font files. I've put them in theme/assets/fonts, and according the mkdoc documentation, extra files in the custom_dir should be applied, but I'm not seeing them being provided. Any help would be appreciated.

Martin Donath

@squidfunk

As far as I know, assets will not be copied over by MkDocs. Just put them in the docs directory and you should be good to go.

Where communities thrive

People

Repo info

Activity

example