squidfunk / mkdocs-material Goto Github PK
View Code? Open in Web Editor NEWDocumentation that simply works
Home Page: https://squidfunk.github.io/mkdocs-material/
License: MIT License
Documentation that simply works
Home Page: https://squidfunk.github.io/mkdocs-material/
License: MIT License
Explain how to amit metrics (Value, Dimesion, Unit)
Hi @squidfunk,
first of all thank you for creating such an awesome theme ๐
After browsing the templates of this theme I saw that you implemented Google Analytics. Would it be possible to integrate tracking with a custom tracking code?
Cheers,
Digitalcraftsman
.article ul li:before {
content: "\e602";
With the above CSS, ordered lists within an unordered list have the content added which overlaps with the number.
See the bottom of these docs for an example: http://d0ugal.github.io/mkdocs-versioned/
The button texts "Prev" and "Next" could be easily made customizable via the mkdocs.yml
, so internationalization is made very easy. This was already requested two times.
Due to white-space: nowrap
defined on th
and td
, table cell continue forever.
Images that are links have a red underline which only really makes sense for text. This can be recreated if you use a simple example like this to add a badge to documentation.
[![PyPI Downloads][pypi-dl-image]][pypi-dl-link]
[pypi-dl-image]: https://img.shields.io/pypi/dm/retrace.png
[pypi-dl-link]: https://pypi.python.org/pypi/retrace
I am trying to use the material theme on readthedocs. I was able to install it; but i still cannot get the material theme up; i get only the default. Any suggestions how to fix this?
I came across this when navigating the Plots.jl
website and clicked on "Examples" expecting it to take me back to the main site:
Since I couldn't I opened an issue, JuliaPlots/Plots.jl#417 after which Tom Breloff pointed me in this direction.
I can understand that breadcrumbs are a bit of a non-feature on a mobile theme, since they take up precious horizontal space. However, if they could be collapsible, like the hamburger menu, then it would make the resulting website easier to navigate on desktops without having to compromise.
It would be awesome to have syntax hightlighting in the code blocks.
If not always then at least configurable in the settings.
Thx for the great theme!
The theme is easily customizable through compilation but it would be nice if there were some more nice material design colors palettes included. Suggestions for good palettes are welcome, maybe one for every color.
When a single mkdocs document has two (or more) h1 headers (# in markdown) โ any headers beneath the second h1 do not show up in the subnav.
Perhaps it's a hint I should use less h1s (single # in markdown), but, assuming it could also be a bug. Might not be one in the rework, haven't had a chance to verify yet.
@squidfunk Do you have a suggested method of using FontAwesome icons with this theme?
I know when I use the ReadTheDocs theme I can use them, however, when I've attempted to implement these using the material theme you've built they simply do not display.
Thanks!
pip install mkdocs-material
mkdocs serve
INFO - Building documentation...
ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'. The available installed themes are: readthedocs, mkdocs
Aborted with 1 Configuration Errors!
If you could make these options and changes, that would be much appreciated!
As of right now, this is one of the best (if not the best) themes for mkdocs. However, there are a few minor problems (as listed above) that can really detract from a site, especially one that isn't a documentation site, but rather a reference/wiki built on mkdocs.
Hello @squidfunk,
it would be useful to implement a back-to-top button if you read a longer documentation page and need to scroll a lot in order to reach the menu at the top again.
If the table of contents for an article is empty (no subheadlines), the parent ul
element is still rendered which adds additional bottom padding.
Fonts don't loads when site\index.html
opens locally. That's because relative protocol link usesd in base.html and there is no file://fonts.googleapis.com/...
data exists.
How about to use https
explicitly?
I was just reading through the docs and thought it probably isn't that clear that Pygments needs to be installed as an extra package for the CodeHilite extension to work. Adding a small mention would be useful.
Either that, or I am missing something ๐
Keystrokes are represented with the kbd
tag. But those aren't directly visible in a larger paragraph. By mocking a button on the keyboard (like on GitHub, e.g. F5) they will be easier to spot.
Adding theme : 'material'
instead of 'readthedocs'
to mkdocs.yml
shows a bunch of warnings about deprecations.
No warnings
ฮป mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
WARNING - Your theme does not appear to contain a 'main.html' template. The 'base.html' template was used instead, which is deprecated. Update your theme so that the primary entry point is 'main.html'.
WARNING - Template variable warning: 'site_name' is being deprecated and will not be available in a future version. Use 'config.site_name' instead.
WARNING - Template variable warning: 'favicon' is being deprecated and will not be available in a future version. Use '{{ base_url }}/img/favicon.ico' instead.
WARNING - Template variable warning: 'repo_url' is being deprecated and will not be available in a future version. Use 'config.repo_url' instead.
WARNING - Template variable warning: 'page_title' is being deprecated and will not be available in a future version. Use 'page.title' instead.
WARNING - Template variable warning: 'canonical_url' is being deprecated and will not be available in a future version. Use 'page.canonical_url' instead.
WARNING - Template variable warning: 'copyright' is being deprecated and will not be available in a future version. Use 'config.copyright' instead.
WARNING - Template variable warning: 'content' is being deprecated and will not be available in a future version. Use 'page.content' instead.
WARNING - Template variable warning: 'google_analytics' is being deprecated and will not be available in a future version. Use 'config.google_analytics' instead.
WARNING - Template variable warning: 'repo_name' is being deprecated and will not be available in a future version. Use 'config.repo_name' instead.
WARNING - Template variable warning: 'page_description' is being deprecated and will not be available in a future version. Use 'config.site_description' instead.
WARNING - Template variable warning: 'site_author' is being deprecated and will not be available in a future version. Use 'config.site_author' instead.
WARNING - Template variable warning: 'current_page' is being deprecated and will not be available in a future version. Use 'page' instead.
WARNING - Template variable warning: 'toc' is being deprecated and will not be available in a future version. Use 'page.toc' instead.
WARNING - Template variable warning: 'next_page' is being deprecated and will not be available in a future version. Use 'page.next_page' instead.
WARNING - Template variable warning: 'include_next_prev' is being deprecated and will not be available in a future version. Use '(page.next_page or page.previous_page)' instead.
WARNING - Template variable warning: 'previous_page' is being deprecated and will not be available in a future version. Use 'page.previous_page' instead.
[I 161120 08:48:50 server:283] Serving on http://127.0.0.1:8000
[I 161120 08:48:50 handlers:60] Start watching changes
[I 161120 08:48:50 handlers:62] Start detecting changes
[I 161120 08:48:52 handlers:133] Browser Connected: http://localhost:8000/
[I 161120 08:48:52 handlers:80] Ignore: c:\python27\lib\site-packages\material\assets\stylesheets\palettes.css
pip install mkdocs
mkdocs new material
cd material
mkdocs serve
python --version
-- 2.7.12mkdocs --version
-- 0.16.0pip show mkdocs-material | grep -E ^Version
-- 0.2.4Custom git url for extra.author.github
It should allow custom URLs for self hosted git servers.
defaults to github
.
When you open documentation, open search bar, close it (with ESC) and then pressing any key on keyboard makes header (logo + social icons) invisible. I can still write in the search bar even it was closed by ESC key.
Sometimes the lines code examples can be very long (e.g. due to indentation ). This creates horizontal scrollbars which isn't ideal for reading. Those could be avoided adding a CSS rule for breaking a line automatically if it doesn't fit.
Hey.
Thanks for making this theme - it's really nice. Read through the open discussion and excited to see you plan to refactor and do a big release in the coming months - looking forward to that.
In the mean time, noticed a bug last night: occasionally the sidebar nav would disappear. If the .md is very long and has a lot of ## through it so that the sidebar nav is too long, when you click on some links it vanishes. Comes back when you scroll though so not critical.
Chrome on Mac in case that's relevant.
Is it possible ta add animation when user click on in docks links. For examle scrolling animation and for example fadein / fadeout. I`m web developer so I can help to achive this feature. Maybe to make this template in angular 2 as one page app?
To replicate:
Should have a lot of sidebar items.
When sidebar's height is greater than the main content height; and when scroll to bottom part of the page.
Inside a block of note or warning the colors of the links are wrong.
A note has a blue link, which don't flatter the eyes. And in a warning you can't tell there is a link.
Just a quick note, when grabbing the latest mkdocs-material release from site (git clone, not via pip), the search functionality is broken due to whatever's going on in application.js on line 1095. This could be user-error in my case, but I follow instructions well.
I wasn't able to narrow down the cause & ended up using the pip installed version's static files to make the customizations I needed.
Edit: Regardless, great work overall! Love the template, and can't wait to launch something with it.
The mkdocs state that the repo_url setting would be used to create a github link on each page.
It would be cool, if this could be added in this theme, too! :)
Hi @squidfunk, first of all: Very good job! I like your theme very much.
I'm writing a manual right now and tried mkDocs with your theme.
It works good, but I had some unexpected behavior:
When not provided with a repo_url, the logo/title are linked to literally: "None".
My expectation is, that it links to the root: "/".
What do you think about this?
Kind regards, Sebastian
Currently, it's not easy to differentiate between fenced inline blocks
and links inside a paragraph. This could be solved by adding a slightly visible background like on GitHub.
Hi @squidfunk,
your theme supports nested menus, e.g. you have many section that contains multiple files that are linked.
This would create a very long menu. Would it be possible to integrate an option that allows users to collapse such sections?
Using the rework
branch, the repo_url
is used to determine the platform. However this detection does not work for platforms if they are self hosted, such as Gitlab.
The developer is able to explicitly state the platform through some means.
The platform is determined from looking at the URL.
gitlab
, github
or bitbucket
Perhaps this could be set via the extras
configuration as repo_type
?
(note that there's also a bug where if the repo_url
is not specified at all mkdocs build
will fail with TypeError: argument of type 'NoneType' is not iterable
)
rework
branch @ 7b585f1The inherent decision that documentation can only be of a GitHub repo is hurtful. This documentation can be used for anything. In my case a WordPress plugin which is not hosted at GitHub.
This area is render useless in my usercase. It would be great if there can extra
options for disabling and enabling the download and stars options or giving the download link or a buy link.
Guys i am trying to use this great looking material theme. As mentioned in instructions i did installation and setup like this.
pip install mkdocs-material
theme: 'material'
in mkdocs.yml
mkdocs serve
Browser did'nt got updated with material theme, instead i am getting this in mkdocs serve logs. Can you please help
INFO - Building documentation...
ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'. The available installed themesare:
[E 161010 01:48:04 ioloop:633] Exception in callback <bound method type.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
Traceback (most recent call last):
File "/usr/local/lib/python2.7/site-packages/tornado/ioloop.py", line 1041, in _run
return self.callback()
File "/usr/local/lib/python2.7/site-packages/livereload/handlers.py", line 66, in poll_tasks
filepath, delay = cls.watcher.examine()
File "/usr/local/lib/python2.7/site-packages/livereload/watcher.py", line 73, in examine
func and func()
File "/usr/local/lib/python2.7/site-packages/mkdocs/commands/serve.py", line 71, in builder
theme=theme,
File "/usr/local/lib/python2.7/site-packages/mkdocs/config/base.py", line 164, in load_config
"Aborted with {0} Configuration Errors!".format(len(errors))
ConfigurationError: Aborted with 1 Configuration Errors!
Hello Martin,
one of users of the Hugo-port noticed that the current CSS code doesn't define any styling rules for blockquotes. Those aren't distinguishable from normal paragraphs.
Cheers,
Digitalcraftsman
Styling of the Admonition extension for Markdown is not correct.
These are the standard colors I see with MkDocs with the standard RTD theme:
note
, seealso
- light blueimportant
, hint
, tip
- greenwarning
, caution
, attention
- beige-browndanger
, error
- pinkwarning
gives red color (instead of beige-brown)mkdocs.yml
:
markdown_extensions:
- admonition
!!! note "Explicit title within double quotes"
Any number of other indented markdown elements.
note
with all of the above mentioned in both projects.I am looking into How Can I Remove the Footer "Docs โ Documentation built with MkDocs using the Material theme." Can anyone let me know? A quick search didn't turnup anything
If the repo_url ends with a slash, like it does in the MkDocs mkdocs.yml the GitHub stars don't work.
repo_url: https://github.com/mkdocs/mkdocs/
We could simply just remove this from the mkdocs.yml, but it would be nice if it worked either way. It took me a few minutes to figure out where the problem was.
This is true for 0.2.1 and the current master version as well (in master only the variable name is changed.)
In base.html we have this portion
{% set favicon = favicon | default("assets/images/favicon-e565ddfa3b.ico") %}
<link rel="shortcut icon" type="image/x-icon" href="{{ base_url }}/{{ favicon }}">
<link rel="icon" type="image/x-icon" href="{{ base_url }}/{{ favicon }}">
I use mkdocs 0.15.3 and material 0.2.1 and I can't get the favicon to stick for the life of me. If I remove that "set favicon" portion and write something like:
{% if site_favicon %}
<link rel="shortcut icon" type="image/x-icon" href="{{ base_url }}/{{ site_favicon }}">
<link rel="icon" type="image/x-icon" href="{{ base_url }}/{{ site_favicon }}">
{% else %}
{% set icon = icon | default("assets/images/favicon-e565ddfa3b.ico") %}
{% endif %}
It works. I am very much a noob and don't understand how that Jinja2 filter is supposed to work but it doesn't work how it's described in the documentation (e.g. just set site_favicon and be done).
Hi,
First off, thank you -- I'm super psyched to see a theme for MkDocs outside of the readthedocs
standard that I both enjoy and find it to work for the style of the documentation I tend to write.
admonition
UI seems a bit too bland, I'm not sure what I'd like to see change, however, I'll give it some thought and update here if I come up with something more concrete. I did see some really cool extensions of the admonition
style used in Microsoft's Office Online docs, however, they're using Sphinx, thought I'd pass this along though. http://wopi.readthedocs.org/en/latest/contributing/style_guide.html. Perhaps use the Material Design icons for alert
, etc in the admonition styles as seen here: https://design.google.com/icons/mkdocs.yml
configurations? I like the Github stars, however, the download
button to me seems like it's a bit unclear as to why a user would download this/what they may be downloading exactly. Something like this may be nice with a bit more material design style: https://github.com/tholman/github-cornersversion
variable. I couldn't find where this is displayed anywhere on the demo site, did I miss something?Once again, I absolutely love this theme and thank you for creating it. I just wanted to provide some thoughts I had when testing it out with one of my mkdocs sites.
I'm happy to help out in any way that I can. Thanks again!
Don't think this is an issue with your project, but I wanted you to know, that you cannot use diacritics in the filename. I reported this to mkdocs: mkdocs/mkdocs#833
As suggested in the official docs, I should be able to modify font size of the theme by using extra.css.
I tried to do it with this theme but it does not work.
This method works with other themes like readthedocs and bootstrap but not this one.
With Chrome v39 (for Anroid) websites are able to change the color of the header bar like native apps on their smartphones and tablets.
You've to add the following one-liner:
<meta name="theme-color" content="PRIMARY THEME COLOR">
For more information take a look at this info page about the new feature.
This issue is meant for updates and discussions on the progress of the rework of the theme. Please feel free to checkout and try the rework branch and comment on the current state of development.
1.0.0-beta
preventDefault
on overlay for iOS when menu is open1.0.0-rc
-webkit-overflow-scrolling
via JavaScript on navigation1.0.0
1.0.x
DONE
Testing
The easiest way to test the rework branch is by downloading or cloning it into your project's root and using the theme_dir
key in your mkdocs.yml
to refer to the theme:
cd your_project
git clone https://github.com/squidfunk/mkdocs-material
git checkout rework
cd ..
In your mkdocs.yml
add:
theme_dir: mkdocs-material/material
Hi, Because of a Japanese work, I needed to move the 'drawer' sidebar. Which element is controlling it?!
Plus: Instead of manipulating original theme css files, is there any option to inject custom css' to the layout via config file (mkdocs.yml)?
Kind regards
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.