Mkdocs-material: Status of 1.0.0

[squidfunk]

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

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

1.0.0-rc

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

1.0.0

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

1.0.x

• [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

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

[squidfunk]

[viktorbenei]

Looks beautiful and quite functional (from a UX point of view)! :+1:

[viktorbenei]

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

[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:

[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

[amadfida]

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

[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 (d3ed8ccec65d340f01a3ea32f359dd0241fa2d20). 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

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

[amadfida]

Thanks Martin for the update.

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

[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 [e-mail]
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
https://github.com/squidfunk/mkdocs-material/issues/46#issuecomment-267838607,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACD5TRK46mlvcNpOagwPlK143Nl-Zujrks5rJYArgaJpZM4J6GPG
.

[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]

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

[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

[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:

[squidfunk]

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

[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]

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

[squidfunk]

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

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

[squidfunk]

I added instructions in the first post of this thread: https://github.com/squidfunk/mkdocs-material/issues/46#issue-176263632

[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?

[squidfunk]

@digitalcraftsman Added in 4ed0b1328fff06e615854d4a443887c5dd769cf0

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

[viktorbenei]

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

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

[amadfida]

Woohoo!!!

• Amad

On Thu, Dec 29, 2016 at 8:34 AM, Martin Donath [e-mail]
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
https://github.com/squidfunk/mkdocs-material/issues/46#issuecomment-269630844,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ACD5TcbKk_IKze1Y7FZtTdxCxXq5h2_bks5rM7bjgaJpZM4J6GPG
.

[brendo]

Excellent!

[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]

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

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

[brianjking]

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

[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:
https://github.com/pallets/jinja/issues/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.

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

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

[Mehran-Baghi]

@squidfunk Sure... #91

[squidfunk]

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

[brianjking]

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

[squidfunk]

We're live!

[StephaneRob]

@squidfunk Thx !

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

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

[digitalcraftsman]

I can only agree - thanks for investing the time to build such an awesome theme :+1: . 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 [e-mail]
wrote:

Great theme! Thanks!

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/squidfunk/mkdocs-material/issues/46#issuecomment-272452094,
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.