squidfunk / mkdocs-material Goto Github PK

Description

Custom git url for extra.author.github

Expected behavior

It should allow custom URLs for self hosted git servers.

Actual behavior

defaults to github.

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

Due to white-space: nowrap defined on th and td, table cell continue forever.

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.

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.

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.

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?

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.

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.

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

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.

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.

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.

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?

Explain how to amit metrics (Value, Dimesion, Unit)

Description

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 table of contents for an article is empty (no subheadlines), the parent ul element is still rendered which adds additional bottom padding.

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.

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
• Added theme: 'material' in mkdocs.yml
• Restarted 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!

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.

• What are your thoughts on having the project logo display either at the top of each page or in the coloured material header when displaying the docs in tablet/mobile view?
• The 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/
• What are your thoughts on adding a "Edit on Github" or "Fork on Github" type option to the 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-corners
• On http://squidfunk.github.io/mkdocs-material/getting-started/ you're showing a version 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!

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?

Description

Adding theme : 'material' instead of 'readthedocs' to mkdocs.yml shows a bunch of warnings about deprecations.

Expected behavior

No warnings

Actual behavior

λ 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

Steps to reproduce the bug

1. pip install mkdocs
2. mkdocs new material
3. cd material
4. 'printf "\ntheme: 'material'" >> mkdocs.yml'
5. mkdocs serve

Package versions

• Python: python --version -- 2.7.12
• MkDocs: mkdocs --version -- 0.16.0
• Material: pip show mkdocs-material | grep -E ^Version -- 0.2.4

System information

• OS: Windows10
• Browser: not relevant

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).

Do you have any plan for prompts to be used in top of page showing some info about the article. They're very useful in wiki pages. Here are some examples:

@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!

The 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.

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.

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?

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! :)

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.

1. Add scroll animation (when you click on a sub header.
2. Add option to remove "Download" and "Stars" Buttons

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.

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 😄

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

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

See it live here.

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.

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.

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.

Hey guys,

I love the theme, but I hate it that hightlighting isn't done by default, and the mentioned extension doesn't work as wel...

I get the following (for PHP):

* Only set and object?*

Please can we add support to this?

1. pip install mkdocs-material
2. 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!

Package versions

• Python: Python 2.7.12
• pip: pip 9.0.1 from .../python2.7/site-packages (python 2.7)
• MkDocs: mkdocs, version 0.16.0
• Material: Version: 0.2.4

System information

• OS: MacOS 10.12.1

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

Thank you for your work

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!

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

• Implement search modal
• Refactor JavaScript
• Integrate Google Analytics from 0.2.x
• Integrate palettes from 0.2.x
• Refactor table styles from 0.2.x
• Create specimen page and check for missing styles
• Add preventDefault on overlay for iOS when menu is open
• Refactor search result code in SCSS

1.0.0-rc

• Put path into header (breadcrumbs)
• Constrain image width to content area (like in 0.2.4)
• Account for height change after parsing MathJax
• Fix bug with non-stretching container when there is no content
• Refactor footer to be variable-size for arbitrary footer content
• Refactor link in footer (together with social icons)
• Include social icons in footer (see #49)
• Check all issues in original Material theme and ensure they are fixed in rework
• Full integration with pymdown extensions
• Write documentation on pymdown extensions
• Fix anchor offsets for blurring
• Add -webkit-overflow-scrolling via JavaScript on navigation
• Add "Edit on GitHub" Link (dependent on mkdocs 0.16 release)
• Make logo/icon configurable (webfont, svg)

1.0.0

• Rewrite getting started guide
• Write documentation on theme extension and customization
• Write documentation on how to integrate theme from GitHub
• Write CONTRIBUTING.md

1.0.x

• Switch to PR-based development workflow after big merge
• Write unit tests with karma for components
• Refactor search algorithm
• Add a separate homepage/langing page layout
• Refactor 404 template
• Fix missing repaint on header/nav for tablet breakpoint

DONE

• Introduced Webpack for more sophisticated JavaScript bundling
• Introduced ESLint and SassLint for code style checks
• Introduced more accurate Material Design colors and shadows
• Introduced modular scales for harmonic font sizing
• Introduced git-hooks for better development workflow
• Rewrite of CSS using the BEM methodology and SassDoc guidelines
• Rewrite of JavaScript using ES6 and Babel as a transpiler
• Rewrite of Admonition, Permalinks and Codehilite integration
• 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 _blank targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
• Removed unversioned assets from build directory
• Restructured templates into base templates and partials
• Added build and watch scripts in package.json
• Added support for Metadata and Footnotes Markdown extensions
• Added support for pymdownx.* Markdown extensions
• Added support for collapsible sections in navigation
• Added support for separate table of contents
• Added support for better accessibility through REM-based layout
• Added icons for GitHub, GitLab and BitBucket integrations
• Added a 404.html error page for deployment on GitHub Pages
• Fixed live reload chain in watch mode when saving a template

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:

1. cd your_project
2. git clone https://github.com/squidfunk/mkdocs-material
3. git checkout rework
4. cd ..

In your mkdocs.yml add:

theme_dir: mkdocs-material/material

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.

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

Description

Styling of the Admonition extension for Markdown is not correct.

Expected behavior

These are the standard colors I see with MkDocs with the standard RTD theme:

• note, seealso - light blue
• important, hint, tip - green
• warning, caution, attention - beige-brown
• danger, error - pink

Actual behavior

• no matter the word, everything is light blue
• only the word warning gives red color (instead of beige-brown)

Steps to reproduce the bug

1. create two projects: one with MkDocs standard and one with Material.
2. mkdocs.yml:

   markdown_extensions: 
     - admonition

3. add this to any .md page:

   !!! note "Explicit title within double quotes"
       Any number of other indented markdown elements.
   

4. play around substituting the word note with all of the above mentioned in both projects.

Package versions

• Python: 2.7.12
• MkDocs: 0.16.0
• Material: 0.2.4

System information

• OS: Windows 10
• Browser: Chrome (I have not tested with other browsers)

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.

.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/

Description

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.

Expected behavior

The developer is able to explicitly state the platform through some means.

Actual behavior

The platform is determined from looking at the URL.

Steps to reproduce the bug

1. Set repo url to something that does not include gitlab, github or bitbucket
2. Note that there is no special treatment to the resulting page.

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)

Package versions

• Python: 2.7.12
• MkDocs: mkdocs, version 0.15.3
• Material: rework branch @ 7b585f1