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