Open discussion and suggestions

[brianjking]

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!

[squidfunk]

Dear Brian,

this theme is considered totally work in progress, so many thanks for your feedback - I really appreciate it! I will try to answer all of your questions:

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?

I started developing the theme in a progressive manner - starting from mobile, going to tablet, then to desktop. I think this is the only way to make it truly responsive. I had to find a way to embed the project logo (because I like to make logos for my projects) in a way that doesn't distract or wastes space, so the drawer on mobile seemed a natural way to go. The fixed header is not really suited, since there is the menu on the left and the search on the right, so no space. I also did not want to put the logo at the top of every page, since the design should be very functional. For desktop I wanted the drawer to stick to the left of the content and scroll in a Facebook-sidebar-manner.

I'm very open for discussion, especially on desktop the menu isn't there and the logo could be embedded into the header. However, project logos are very diverse and the only constraint I felt was manageable was a rectangular logo. Do you have any ideas how we could improve logo positioning? I have the idea of making the theme configurable in terms of layout, so we really could incorporate some further options/tuning

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/

This is something that I added more or less in a hurry and that isn't really thought through. Your points seem pretty valid and I like your proposals! One thing to consider is that the class (e.g. note, hint or warning) are not well-defined, as the user can choose any name he likes. However, we could define hint/note as a base class with the flag, and warning with the alert icon. I will work it into the theme. If you have some time, feel free to sketch out some further ideas on that (should we stretch it to the border on mobile/tablet? something I'm also not very decided on)

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?

You can specify it via the extra.version variable
http://squidfunk.github.io/mkdocs-material/getting-started/#adding-a-version

[squidfunk]

Forgot one:

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

The download button was inspired by the GH pages themes - they all have them. The problem with the download button is mainly that you would download the master, and not the latest tagged release. I haven't found out whether GitHub offers an API call for "Latest release". This would actually make sense I think. Could you elaborate on what the specific buttons you mentioned should do?

The corners design works on desktop only with a resolution bigger than ~1250px, so how would we solve this on mobile? It's also something I thought about, but it didn't work for me.

[squidfunk]

Oops, referenced the wrong issue in the last commit. Reopening it. Do you have any thoughts on my comments, Brian?

[sebastian-marinescu]

I also have some suggestions/ideas:

• minimize the padding-top of .article .wrapper to something like 92px, so that the main-headline and the logo/header line up nicely, imho it's a little too much white-space and doesn't look to good, if there are no buttons (it's not disturbing in your demo, because of the buttons I think)

• don't render an empty <ul></ul> if there are no children-pages
  it gets a margin-bottom from .drawer .current+ul

• allow the !!! note and !!! warning blocks to have different labels. I tested !!! MyNote and it works (because you probably fall back to the note-template). But this doesn't work with the warning class. Something like !!! warning('My Custom Warning') would be very handy. My main intention is, that I don't write the documentation in English but in German, and I'd like to be consistent.

• I like the idea to just drop in folders and .md-files and that mkDocs just scans it and builds the navigation from it. But I also like control. Inside these folders I prepend numbers before the files, so that they are ordered like I want (0-Overview, 1-Guidelines, 2-Etc) inside the folder and inside the menu. But I don't want to to see the numbers in the build. Also I noticed, that the yaml-block in the md-files gets parsed.

  So how about adding an option to influence the title from the yaml-block inside the md-file? And if the parser finds this option it uses this (for the navigation- and pagination-links and the pagetitle), if not it uses the file-name like right now.

An example of the suggestions could look something like this:

---
title: Some Title for menu/pagination/pagetitle instead of filename
---

# Main Headline
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor 
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis 
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

!!! warning('Important')
    Access allowed only to administrators.

[squidfunk]

minimize the padding-top of .article .wrapper to something like 92px, so that the main-headline and the logo/header line up nicely, imho it's a little too much white-space and doesn't look to good, if there are no buttons (it's not disturbing in your demo, because of the buttons I think)

Currently it's aligned to the buttons yes. I tried your suggestion but it doesn't convince me yet. I'm not 100% happy with the project section in the drawer yet – there are so many cases (repo, version, logo) one has to optimize for. I will leave it as it is for now, but you can easily adjust it, if you think it doesn't work for you. If you have suggestions regarding the project drawer - feel free to comment.

don't render an empty

if there are no children-pages it gets a margin-bottom from .drawer .current+ul

Good point, will convert this to an issue and fix it.

allow the !!! note and !!! warning blocks to have different labels. I tested !!! MyNote and it works (because you probably fall back to the note-template). But this doesn't work with the warning class. Something like !!! warning('My Custom Warning') would be very handy. My main intention is, that I don't write the documentation in English but in German, and I'd like to be consistent.

This is already possible:

!!! warning "Don't try this at home"

See the admonition documentation for more options.

I like the idea to just drop in folders and .md-files and that mkDocs just scans it and builds the navigation from it. But I also like control. Inside these folders I prepend numbers before the files, so that they are ordered like I want (0-Overview, 1-Guidelines, 2-Etc) inside the folder and inside the menu. But I don't want to to see the numbers in the build. Also I noticed, that the yaml-block in the md-files gets parsed.

So how about adding an option to influence the title from the yaml-block inside the md-file? And if the parser finds this option it uses this (for the navigation- and pagination-links and the pagetitle), if not it uses the file-name like right now.

The Markdown parser used by MkDocs doesn't allow for front matter, so it's not possible at the moment. Maybe there are already plans on allowing front matter, I don't know.

[squidfunk]

Fixed rendering of empty table of contents in #5

[sebastian-marinescu]

Currently it's aligned to the buttons yes. I tried your suggestion but it doesn't convince me yet. I'm not 100% happy with the project section in the drawer yet – there are so many cases (repo, version, logo) one has to optimize for. I will leave it as it is for now, but you can easily adjust it, if you think it doesn't work for you. If you have suggestions regarding the project drawer - feel free to comment.

I'm also not sure what would be best, it just stuck a little in my eyes. I'll think about it while I document more and have looked enough at it 👍

Good point, will convert this to an issue and fix it.

Nice!

This is already possible:
!!! warning "Don't try this at home"
See the admonition documentation for more options.

Awesome, thank you!

Also nice to see you can have a admonition-box without a title:

!!! important ""
    This is a admonition box without a title.

The Markdown parser used by MkDocs doesn't allow for front matter, so it's not possible at the moment. Maybe there are already plans on allowing front matter, I don't know.

Okay, I see. Maybe in the future then. I solved my issue with this by using a filename-schema like this:

1. Overview
2. My Awesome Title
3. Something

This looks good on the filesystem and also in the navigation.

[max-ci]

Hi,

Did you think about renaming warning admonition to danger and add warning with yellow background?

[squidfunk]

I would say warning should be the highest priority, thus red. We could think about defining a little less severe variation of warning in yellow color, but you can also easily do it yourself and most people may not need it. If you create an admonition note with another name, you can easily define the styles via CSS. That's how warning is defined.

[squidfunk]

Jep, I can reproduce it, thanks for reporting! Could you open an issue for this one?

[versedi]

Hi,

This is a real nice theme, great job.

1. Wraps inside tables

One thing that I've had to modify manually in my case was white-space: nowrap set on every td/th inside .article.
Somehow extra.css was overwritten in this case even when the element was specified very much, i.e.

.data table.table .article table td, table.table .article table th {
    white-space: wrap ! important;
}
body .article table td
{
    white-space: wrap !important;
}
.article table#csv td, .article table#csv th, .table-condensed td {
    white-space: wrap !important;
}

Only way to solve this for me was to simply remove the styles for that inside theme's css. This was required for me cause of a lot descriptions inside table cells.

Warning Dangers

IMHO
a. danger - red
b. warning - orange/yellow

I'll get back here with more feedback ;)

[squidfunk]

One thing that I've had to modify manually in my case was white-space: nowrap set on every td/th inside .article.

This is indeed a bug. I will open an issue and fix it asap.

[squidfunk]

Oh and in general I've come up with some ideas concerning the optimization of the layout. Some points to address in my opinion are:

1. Bigger font sizes
2. A better solution for the drawer on desktop
3. Some design fixes / make it a little cooler

I will create a new experimental branch for this and we can discuss further ideas here.

[squidfunk]

Just wanted to let everyone know: I'm currently actively working on the experimental branch and push it to GitHub, as soon as it basically works. I was on vacation for three weeks, so this is why it was rather calm in the last time.

[squidfunk]

Preview: collapsing header, larger typography (following best practices for the web with 35-40 characters per line on mobile), vertical rhythm (because documentation is all about comfortable reading). Still heavily in progress.

[digitalcraftsman]

@squidfunk the awesome preview above made me curious (again). Do you have more to show?

[squidfunk]

@digitalcraftsman I'm working on it on a week-by-week basis. I have a new client that keeps me busy for 90% of my time until the end of July (or longer), so progress is rather slow at the moment, but as soon as it's worth checking out, I will push it to a new branch.

[digitalcraftsman]

Thank you for posting this update. I don't want to urge anyone.

[brianjking]

@squidfunk Also, appreciate it! Thanks!

[ijy]

Is this built using Material Design Lite or one of the other material UI frameworks?

[squidfunk]

@ijy nope, it's built from scratch. I'm not a big fan of those material UI frameworks. Most of them depend on jQuery, which I personally hate, plus they inhibit rendering bugs for some of the UI components on some platforms. Especially iOS. Therefore I built everything from scratch.

[viktorbenei]

Re: "What are your thoughts on adding a "Edit on Github" or "Fork on Github" type option to the mkdocs.yml configurations?"

To provide a bit of context why this can be quite important, as it is for us: we're working on a complete revision of our docs, and we decided to move our docs back to a git/GitHub based solution (MkDocs), mainly for two reasons:

1. We love to work with git and markdown / text based documents, whenever we can we prefer to use it over a service.
2. We love how easy it is to edit a document & send a Pull Request on GitHub

We do PR reviews on Docs too, and we want to make our docs as open as possible, with a simple workflow for outside collaborators / anyone to send fixes, corrections or new material (our docs includes guides / tutorials / tips & tricks, not just pure documentation).

We decided to use MkDocs this time and so far we love this material theme! Our only issue with it is that it lacks the "Edit on GitHub" feature, which is available in the ReadTheDocs theme. You can see an example here: http://read-the-docs.readthedocs.io/en/latest/builds.html - top right corner.

Ideally the link would even open the related document in edit mode - e.g. instead of https://github.com/rtfd/readthedocs.org/blob/master/docs/builds.rst it would open https://github.com/rtfd/readthedocs.org/edit/master/docs/builds.rst

You can find the related MkDocs discussion at mkdocs/mkdocs#269

IMO the best solution would be to allow an additional configuration option like github_url and bitbucket_url, or github_edit_base_url, and if this is set then the "Edit on GitHub/Bitbucket" button/link would be shown on every page, around the top right corner. If the user clicks on the link it would open the related document's GitHub/Bitbucket edit page directly.

This would help a lot in encouraging everyone to fix minor issues like typos, or to add more information / context. E.g. http://apidock.com/rails/ActiveRecord/Batches/ClassMethods/find_each has a comment section where users can add more info related to different use cases, but we think that's not integrated enough, and that allowing users to add these information into the docs (via Pull Requests) would be even more useful.

Thanks again for the wonderful theme, and let us know what you think about this feature. We'd be glad to help with the development too.

[squidfunk]

Thank you for your feedback. I understand the requirements, but I think it's not possible to generate it automatically with MkDocs, because there is no information regarding the underlying file available in the template, so first MkDocs would need to be extended. RTD can do it, because they pull the documentation from GitHub and have written some sort of layer on top of Sphinx and MkDocs. Maybe you can open a feature request for this on the MkDocs repository? Or maybe first talk to @d0ugal.

[viktorbenei]

Thanks for the quick response!

I think the discussion is already open (mkdocs/mkdocs#269) and it seems that it should already be implemented.. But I can't find any info about it (no docs, no release notes), so it might still be under development.

[squidfunk]

Hmm, for me it reads more like they didn't implement it.

[viktorbenei]

I left a question there, hopefully they'll clarify whether this feature is still planned for an upcoming 0.15.x release

[viktorbenei]

Just a status update for the "Edit on GitHub/Bitbucket" feature - the related PR was just merged mkdocs/mkdocs#975 so this should be available in the next version of MkDocs

[squidfunk]

Progress is slow, but steady again - got inspired by the Google Developer documentation style a lot, borrowing the best parts..., including elastic sidebars - better than the currently bouncing style.

[viktorbenei]

Looks awesome @squidfunk ! 😉

[squidfunk]

I pushed the current state to a new branch called rework. It's far from being finished, especially the mobile and tablet views need some work and the search is non-functional. However, nevertheless some progress.

The main idea behind the rework is to massively increase readability (larger type, narrower lines), because that is what docs are for. Feel free to checkout and comment (see http://squidfunk.github.io/mkdocs-material/customization/ for setup guidelines).

What I have done so far:

• complete rewrite of JavaScript as transpiled ES6
• complete rewrite of CSS using the BEM methodology
• elastic sidebars
• better typography
• complete rem-based layout
• rework of syntax highlighting

What's next:

• Finish navigation sidebar (collapsing sections are kind of beta)
• Implement mobile style for sidebar and table of contents
• Implement search modal
• Integrate links to source repositories
• Lots of small improvements

[brianjking]

@squidfunk Thanks for the update, keep up the great work. Can't wait to try out the new version once it's released.

[squidfunk]

I'm currently working on the new admonition concept for the rework branch. Some of you wanted more diverse admonition tool tips. Here is what I came up with:

"Hint/Note" is the default. "X/Y" means that both names can be given, they are synonyms. Feel free to give me feedback on the types of admonition styles and the synonyms.

[brianjking]

@squidfunk The admonition styling is gorgeous, great job! I'd love to see these released on their own even if you don't have the rest of the updates ready.

[sebastian-marinescu]

Hi @squidfunk nice job again. I will be cloning your rework-branch into my current doc-project and check it out :) @brianjking You should do the same, if you want the latest features ;)

[squidfunk]

Thanks to both of you. My time is very limited at the moment, so I regret, but the admonition styles won't make it into the current version. I'm currently reworking the search whenever I have the time to provide a better search experience. This is the last big blocker, next to some minor visual changes. Then I can make a first release candidate. However, PyPI doesn't support beta or pre releases, so to use it, you have to clone it anyway. I will finally release it, when the polishing is finished.

[squidfunk]

Oh and feel free to comment on everything you notice on the rework branch here. Please don't make new issues for now but use this thread, since it's not even considered production-ready.

[sebastian-marinescu]

Hi Martin, but the admonition-styles are already in the rework-branch, or
not? :)

Sebastian G. Marinescu
// Consulting & Development

T +49 (0) 69 20 165 681 <+496920165681>
F +49 (0) 69 20 165 682
M +49 (0) 178 83 48 389 <+491788348389>

connect with me
via Xing https://www.xing.com/profile/SebastianG_Marinescu or LinkedIn
https://www.linkedin.com/pub/sebastian-g-marinescu/b7/5b5/291

Diese E-Mail enthält vertrauliche und/oder rechtlich geschützte
Informationen. Wenn Sie nicht der richtige Adressat sind oder diese E-Mail
irrtümlich erhalten haben, informieren Sie bitte sofort den Absender
und vernichten Sie diese Mail. Das unerlaubte Kopieren sowie die unbefugte
Weitergabe dieser E-Mail ist nicht gestattet.

This e-mail may contain confidential and/or privileged information. If you
are not the intended recipient or have received this e-mail in error please
notify the sender immediately and destroy this e-mail. Any unauthorized
copying, disclosure or distribution of the material in this e-mail is
strictly forbidden.

On Thu, Sep 1, 2016 at 12:32 PM, Martin Donath notifications@github.com
wrote:

Oh and feel free to comment on everything you notice on the rework branch
here. Please don't make new issues for now but use this thread, since it's
not even considered production-ready.

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#2 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/ADn3Vwy_gZ9r3aPawL_YOYOufG7tRTucks5qlqm6gaJpZM4HXR7i
.

[squidfunk]

No, they're not 100% ready. I will try finishing them tonight and drop you a note when I pushed them to the rework branch.

[sebastian-marinescu]

Sounds great. Didn't want to pressure you - so just drop me/us a note, when you have them in :)

[squidfunk]

The following changes were pushed to the rework branch

• New admonition styles (alpha)
• Removed bower as a dependency
• Material Icons are now loaded from Google Fonts, so all icons can now be easily used from within documentation
• Prototyped new search bar (non-functional)
• Switched to other Material color and shadow SASS libraries for better results (colors didn't perfectly match the Material color palette)
• Switched to ligature-based icon embedding approach

[brianjking]

@squidfunk Thanks! Keep up the awesome work...

Can I just add git+https://github.com/squidfunk/mkdocs-material.git@rework to my requirements.txt file to use the rework branch?

Any ideas? @sebastian-marinescu

[squidfunk]

@brianjking: I did a quick search and found this, maybe it helps:
http://stackoverflow.com/a/16584935/1065584

However, note that the rework branch is far from being production ready. Search is non-functional and the mobile drawer is unfinished. I'm currently working on them, though.

[squidfunk]

I will close this issue for now, since all is headed towards the new 1.0.0. A separate issue – #46 – has been created to allow discussion on 1.0.0.

[viktorbenei]

@squidfunk heads up about the "Edit on GitHub" - it seems this feature shipped in the latest MkDocs (0.16.0 - http://mkdocs.readthedocs.io/en/latest/about/release-notes/#other-changes-and-additions-to-version-0160) version as edit_uri configuration option - http://www.mkdocs.org/user-guide/configuration/#edit_uri