Status of 1.0.0 about mkdocs-material

[squidfunk]

Just released the beta version of 1.0.0. Feel free to check it out and post feedback here. As usual, the easiest way is to clone it into a subfolder of your project and reference the theme with theme_dir.

The majority of open tasks for a final release of 1.0.0 are related to documentation or small bugs that I will address in the next days.

[squidfunk]

[squidfunk]

No, on mobile the table of contents is embedded in the navigation in a multi-layered (more mobile friendly than now) menu. I've got it ready, only have to implement the search modal and do some cleaning up.

This is the current WIP:

[amadfida]

any update on this ? we have a downstream project we depend on that could use this update.

[squidfunk]

Oh and thank you all for the great collaboration. So many bugs filed that could be fixed prior to the release because of the extensive testing you guys did before. You guys are awesome!

[viktorbenei]

All right. So a quick bug report for the beta version - images are not restricted to the width of the content area like before:

With 1.0.0-beta:

With current release (0.2.4):

[squidfunk]

@viktorbenei Fixed in 7702904

[squidfunk]

The release candidate is finally out:
https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0-rc

Everyone, please validate all issues are fixed in the release candidate and check it with your docs. If you come across something, please post it here. Otherwise, I will push out the final release two weeks from now (if no critical issues are found), so on the 12th of January.

EDIT: I deployed the docs for my project protobluff using the latest template as a showcase:
http://squidfunk.github.io/protobluff/

[omenos]

Just wanted to pop in here, as I've been using the material theme for a project since I found mkdocs a couple of months ago. I just tested 1.0.0-rc2 with my current documentation site and man is it beautiful! Worked like a charm right off the bat, and makes the whole site look a lot better. And it fixed a bug I was having with code blocks where each line would have the grey backdrop on top of the overall block background.

Nice work! Can't wait for it to become the master branch!

[squidfunk]

Everything is prepared. I will release 1.0.0 here on GitHub and PyPI tomorrow. This will equal the current master.

[squidfunk]

We're live!

[squidfunk]

@amadfida I updated the list with more detailed tasks that have to be done in the different phases. I will try to accomplish everything within the next week to release 1.0.0-rc.1, because I will be on vacation from 18 Nov to 12 Dec. The RC can then be tested and we should be able to push 1.0.0 out at the end of the year. Sorry for the delay and the promises on releasing 1.0.0 soon, but sometimes other things in life need some more attention than a spare time project. However, everything will be okay in the end and I think the result will surpass 0.2.4 by far.

[squidfunk]

Just released the second beta for 1.0.0 which equals the current master. Feel free to test and comment.

[squidfunk]

Just released release candidate 3:
https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0-rc.3

Moved the final release date by one day to Friday the 13th. Let's jinx it.

[viktorbenei]

Looks beautiful and quite functional (from a UX point of view)! 👍

[markallasread]

It appears pymdownx-extensions 1.2 is required for the 1.x branch/pre-release.
Gave me a hint of trouble, might be worth tossing it in the readme as a requirement.

(I'd submit it myself but no time right this very moment)

Edit: Note — great work! Just digging in now, looks like a massive upgrade though, and a nice clean design to boot.

[viktorbenei]

Just found another one: the left sidebar slides under the footer if the content is shorter than the sidebar - which makes the bottom items unaccessible:

[viktorbenei]

Sure it is - https://github.com/bitrise-io/devcenter - but I only tried the rework branch locally for now, the way you mentioned ("As usual, the easiest way is to clone it into a subfolder of your project and reference the theme with theme_dir.")

[squidfunk]

I added instructions in the first post of this thread: #46 (comment)

[squidfunk]

@digitalcraftsman Added in 4ed0b13

[viktorbenei]

Just tried out the latest from rework with our docs site, and everything seems to be working properly now 👍

[brianjking]

@squidfunk Using the pre-release 1.0.0-rc2 on ElementaryOS I was able to runnpm install and npm run build successfully.

[Mehran-Baghi]

@squidfunk Sure... #91

[brendo]

Many thanks for your efforts @squidfunk, you should be very proud of what you have achieved. 🍻

edit: just rolled this out internally across ~10 different sites without issue!

[viktorbenei]

Just a question, how will this look like on mobile? Will there be two side menus?

[viktorbenei]

Looks awesome!

The current mobile view was "good enough" as well - the main pain point was to jump to sub sections - this design seems to solve that ;)

[squidfunk]

The current mobile view was "good enough" as well - the main pain point was to jump to sub sections - this design seems to solve that ;)

Because the menu was too long or what do you mean? The pages of a subsection are now included in a new pane which slides in when pushing one of the buttons with the chevron, e.g. "Extensions" brings up "Codehilite", "Permalinks", etc.

[viktorbenei]

Mostly because if you selected a main section, and then you wanted to select a subsection of it, you had to scroll through lots of items in the menu again, to be able to select the sub section

Example from our DevCenter: https://bitrise-io.github.io/devcenter/caching/about-caching/#downloading-and-deleting-caches - try to select this sub section from https://bitrise-io.github.io/devcenter/ , right now you have to scroll through the menu two times, as every main an secondary section is listed, but 3rd level sections are only shown when you click the related secondary section.

If I understand it correctly, with the new design only main sections will be listed, which should make the menu significantly shorter. In our case this will mean less scrolling ;)

[squidfunk]

The new design puts the current subsection path as separate panes (one for each node in the tree) over each other, so when you are on the third level, there are three panes over another. Additionally, the subsection of the current entry is open on page load and highlighted in the accent color showing a table of contents icon. When you click on the entry, the table of contents opens in another pane. That's the basic idea and I think it works very well for short and long docs on mobile.

[viktorbenei]

I agree, this seems to be a great improvement for our site too ;)

[ahmadawais]

@squidfunk I tried installing the rework theme but it gave errors. How can I try it?

[squidfunk]

Can you elaborate on what errors exactly? And please, the next time you post an issue stick to the issue template.

[ahmadawais]

@squidfunk I didn't follow the template since the info it asked for had no say in a general feature request (it was not a bug complaint). But sure I will next time.

So, I cloned the repo and checked out to rework branch. Then I used theme_dir variable in the mkdocs.yml to point to the new theme's folder i.e. material_rework/material

Then I rand mkdcos serve which leads to the following output

INFO    -  Building documentation...
INFO    -  Cleaning site directory
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 11, in <module>
    sys.exit(cli())
  File "/Library/Python/2.7/site-packages/click/core.py", line 716, in __call__
    return self.main(*args, **kwargs)
  File "/Library/Python/2.7/site-packages/click/core.py", line 696, in main
    rv = self.invoke(ctx)
  File "/Library/Python/2.7/site-packages/click/core.py", line 1060, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Library/Python/2.7/site-packages/click/core.py", line 889, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Library/Python/2.7/site-packages/click/core.py", line 534, in invoke
    return callback(*args, **kwargs)
  File "/Library/Python/2.7/site-packages/mkdocs/__main__.py", line 115, in serve_command
    livereload=livereload,
  File "/Library/Python/2.7/site-packages/mkdocs/commands/serve.py", line 78, in serve
    config = builder()
  File "/Library/Python/2.7/site-packages/mkdocs/commands/serve.py", line 74, in builder
    build(config, live_server=True, clean_site_dir=True)
  File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 289, in build
    build_pages(config)
  File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 233, in build_pages
    build_template('404.html', env, config, site_navigation)
  File "/Library/Python/2.7/site-packages/mkdocs/commands/build.py", line 148, in build_template
    output_content = template.render(context)
  File "/Library/Python/2.7/site-packages/jinja2/environment.py", line 989, in render
    return self.environment.handle_exception(exc_info, True)
  File "/Library/Python/2.7/site-packages/jinja2/environment.py", line 754, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/Users/USER/Documents/Websites/clone/docs/material_rework/material/404.html", line 1, in top-level template code
    {% extends "base.html" %}
  File "/Users/USER/Documents/Websites/clone/docs/material_rework/material/base.html", line 36, in top-level template code
    {% include "partials/header.html" %}
  File "/Users/USER/Documents/Websites/clone/docs/material_rework/material/partials/header.html", line 27, in top-level template code
    {% include "partials/source.html" %}
  File "/Users/USER/Documents/Websites/clone/docs/material_rework/material/partials/source.html", line 1, in top-level template code
    {% if "github." in repo_url %}
TypeError: argument of type 'NoneType' is not iterable

[squidfunk]

Collapsible sections are implemented in 1.0.0, but will not be a part of 0.2.4 due to my constrained time. I'm working hard in my spare time to finish 1.0.0, but it may still take some time, I'm very sorry.

[urosjarc]

@amadfida If your project is dependent of this update why don't you contribute to this project to push version 1.0.0 to completion. Also @squidfunk I would suggest for 1.0.0 to make kanban like todos in project section It will make contribution much easier... my example. I can help you with karma tests.

[squidfunk]

Thank you for the offer, but there's still some cleanup to do for me before we can do this together in a way that makes sense. Will do it after relasing the next version :-)

[MaciejCaputa]

I find it very useful to be able to print a mkdocs website with material theme and save it as PDF document. At current version there are some media print statements, but I still find myself adding an extra_css to adjust how the document will be formatted when printed/saved to pdf. Can we ensure that the version 1.x.x will have natively print media queries in css that will adjust the styles as well? I don't mind contributing and doing it myself or helping you in some other way.

BTW. I really appreciate your work. The current version of the theme is great and the 1.0.0 is even more promising. Can't wait for official release. ;)

[squidfunk]

@MaciejCaputa Thanks! I added basic print styles in the last commit (d3ed8cc). Feel free to test it and contribute your adjustments. I would love to hear about your extra stylesheets, because maybe it's of use for all of us :-)

[amadfida]

@squidfunk when you get a chance, do you mind updating the status of TODO list at the beginning of this issue - Based on your comment it seems like you are making good progress and some of them may already be done. Thanks

[amadfida]

Thanks Martin for the update.

[viktorbenei]

Awesome news, thank you @squidfunk!

[amadfida]

Martin, Great news and thanks for all of your hardwork. Amad - Amad

…

On Sun, Dec 18, 2016 at 10:49 AM, Viktor Benei ***@***.***> wrote: Awesome news, thank you @squidfunk <https://github.com/squidfunk>! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACD5TRK46mlvcNpOagwPlK143Nl-Zujrks5rJYArgaJpZM4J6GPG> .

[viktorbenei]

@squidfunk where should we report bugs/issues for 1.0.0? Create GitHub issues with some [1.0.0] like tag? What would you prefer?

[squidfunk]

I would say we stick to this thread for now, because all other issues refer to 0.2.x and this might confuse visitors.

[squidfunk]

Is the project hosted on GitHub? In order to fix it I need to reproduce it.

[squidfunk]

@viktorbenei I suspect that the problem originated from the fact that the page includes some images. The bounds of the sidebar were only calculated upon initialization, which means before the images were loaded, so afterwards the height of the image was added to the height of the container but the height for calculation was not updated. Now they are updated continuously so the problem should theoretically be fixed in current master. Can you elaborate?

Furthermore the problem when the main content is shorter than the sidebar is fixed, the sidebar should now always stretch to the visible height.

[brianjking]

@squidfunk What's the best way to test this release with one of my existing MkDocs sites?

Thanks for all your hard work! Happy Holidays, cheers.

[digitalcraftsman]

In the first version of your theme users could leave the search with the escape key. Could you add this behavior again to version 1.0.0?

[brianjking]

@squidfunk Should the TOC be collapsed by default? In 0.2.4 it shows this expanded.

[squidfunk]

I would say yes, at least for orientation. When opening the drawer on mobile/tablet the user decides whether to navigate on the current page (toc) or within the whole documentation.

[squidfunk]

Tomorrow, I will push out the release candidate for 1.0.0.

[amadfida]

Woohoo!!! - Amad

…

On Thu, Dec 29, 2016 at 8:34 AM, Martin Donath ***@***.***> wrote: The release candidate is finally out: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0-rc Everyone, please validate all issues are fixed in the release candidate and check it with your docs. If you come across something, please post it here. Otherwise, I will push out the final release two weeks from now (if no critical issues are found), so on the 12th of January. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACD5TcbKk_IKze1Y7FZtTdxCxXq5h2_bks5rM7bjgaJpZM4J6GPG> .

[brendo]

Excellent!

[squidfunk]

The build is currently broken due to a strange bug. I already filed an issue:
mkdocs/mkdocs#1121

Does any of you tried to build the theme on Linux? Travis suddenly fails.

[squidfunk]

@brianjking thank you. Can you also try it with the rework branch?

[StephaneRob]

Looks like a Jinja2 issue. Tried on OSX with the last jinja2 version (2.9.1) and get same error.
Tested with Jinja2 2.8 without any issue.

[squidfunk]

An issue was already filed for this error:
pallets/jinja#640

Let's monitor it and hope for a quick fix.

[brianjking]

@squidfunk Sure, I'll try later today as I have to head out to an appointment in just a minute.

[brendo]

Looks like Jinja 2.9.2 has been released which should resolve the issue.

[squidfunk]

The build was fixed with the latest commit.

[Mehran-Baghi]

Thank you for this beautiful theme. I'm very excited to see the final release.
I had issues with anchor links (permalinks?). Let's say I want to link to a citation in the footnote of my document. I use <a name="Reference-1">1. Reference Description</a> to define the anchor point in the footnote and I link to that by [1](#Reference-1)
In the default mkdocs theme it lands exactly where I put the anchor, however in material theme (both rework and master) it lands few lines blew. So how to fix that? Or what are the best practices for citation?

[squidfunk]

@Mehran-Baghi can you please file an issue with a Markdown example to reproduce? Please stick to the issue template.

[brianjking]

@squidfunk Awesome, can't wait! Thank you for all your hard work!

[StephaneRob]

@squidfunk Thx !

[digitalcraftsman]

I can only agree - thanks for investing the time to build such an awesome theme 👍 . I'll try to port your new version to Hugo.

[facelessuser]

Great theme! Thanks!

[amadfida]

+1 great work Martin. - Amad

…

On Fri, Jan 13, 2017 at 6:14 AM, Isaac Muse ***@***.***> wrote: Great theme! Thanks! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#46 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ACD5Tb2rgQaYd-Xqw_CK2nIXGqEQ19J_ks5rR4bTgaJpZM4J6GPG> .

[max-ci]

Thank you again for amazing work!

Just a small issue.

Are you sure about webkit-font-smoothing: antialiased?

For me it doesn't look good (less readable) when we have dark background (footer) and small white text (Chrome/Mac - I don't know how it looks on Windows). It looks good on Firefox/Mac (with moz-osx-font-smoothing: grayscale).

Please Stop "Fixing" Font Smoothing

---

[squidfunk]

In my opinion it looks great, even on a non-Retina display. When I turn it off, everything looks pretty bold and jagged.

[squidfunk]

Closing this issue. Please create separate issues again for bugs and feature requests.