Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

馃殌 Material for MkDocs 5.0.0 RC 4 #1498

Open
squidfunk opened this issue Mar 10, 2020 · 164 comments
Open

馃殌 Material for MkDocs 5.0.0 RC 4 #1498

squidfunk opened this issue Mar 10, 2020 · 164 comments
Labels

Comments

@squidfunk
Copy link
Owner

@squidfunk squidfunk commented Mar 10, 2020

Help test Material 5 RC 4! Deploy preview

Please post any problems you encounter during migration in this issue.

Installation

Using pip:

pip install "mkdocs-material>=5.0.0rc4"

Using docker:

docker pull squidfunk/mkdocs-material:5.0.0rc4

Features

  • Reactive architecture 鈥 try __material.dialog$.next("Hi!") in the console!
  • Instant loading 鈥 make Material behave like a Single Page Application!
  • Improved CSS customization with CSS variables 鈥 define your CI colors!
  • Improved CSS resilience, e.g. proper sidebar locking for customized headers
  • Improved icon integration and configuration 鈥 now including over 5k icons!
  • Added possibility to use any icon for logo, repository and social links
  • Search UI does not freeze anymore (moved to web worker)
  • Search index built only once when using instant loading
  • Improved extensible keyboard handling
  • Support for prebuilt search indexes
  • Support for displaying stars and forks for GitLab repositories
  • Support for scroll snapping of sidebars and search results
  • Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
  • Slight facelifting of some UI elements (Admonitions, tables, ...)

Fixed in RC 2

Fixed in RC 3

  • #1515: Return link of footnote not show after convert to pdf enhancement
  • Fixed Admonitions for print media
  • Fixed Details for Safari (iOS and macOS)
  • Fixed hover states for nested items in mobile navigation
  • Improved rendering performance
  • Improved social icons and copyright notice alignment
  • Improved accessibility

Fixed in RC 4

  • Fixed #1544: Move logo into partial for easier overriding enhancement 鈥 c9b2c1e
  • Fixed #1518: Allow configuration of default search query pre-processing function enhancement 鈥 64caf62
  • Fixed #1507: Instant loading scroll restoration bug 鈥 4d370fe
  • Fixed #1451: Nested PDFs and SVGs seem to be ignored as page content bug 鈥 42524ae
  • Fixed replacement of skip link and announcement bar on instant load 鈥 908d34b
  • Fixed bug where a popstate event triggered history.pushState again
  • Fixed header ellipsis when title equals site name
  • Fixed hover states of search input for black and white palette
  • Removed required attribute on search input
  • Improved global keyboard events to only emit when not in editable element
  • Improved color customization of details arrow icon
  • Improved copy-to-clipboard button sizing in Admonitions

Migration

See the migration guide in the deploy preview.

@fkorotkov

This comment has been minimized.

Copy link

@fkorotkov fkorotkov commented Mar 10, 2020

@squidfunk will you publish an RC Docker image as well?

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Mar 10, 2020

@fkorotkov just pushed the Docker image, see OP.

@SM-26

This comment has been minimized.

Copy link

@SM-26 SM-26 commented Mar 11, 2020

Hey, I'm having some issues with custom logos/icons.

If I want to use my own PNG/SVG, where should I put it in?

this is my mkdocs.yml:

theme:
  name: material
  custom_dir: 'theme'
  language: en
  feature:
    - instant
    - tabs
  palette:
    primary: 'blue grey'
    accent: 'red'
  # font:
    # text: 'Roboto'
    # code: 'Ubuntu Mono'
  icon:
    logo: "assets/images/android-chrome-256x256.png"
  favicon: "assets/images/safari-pinned-tab.svg"

and in my directory looks like this:

docs
- index.md
- robots.txt
-sitemap.xml
theme
- assets
-- javascripts
-- stylesheets
- icons
-- assets
--- images
---- android-chrome-256x256.png
---- android-chrome-256x256.png.svg
- main.html

but I still get error

raise TemplateNotFound(template)
 jinja2.exceptions.TemplateNotFound: .icons/assets/images/android-chrome-256x256.png.svg
 ERROR: Job failed: exit code 1

Where is ".icons".?

Thanks in advance.

@diba1013

This comment has been minimized.

Copy link
Contributor

@diba1013 diba1013 commented Mar 11, 2020

I followed your migration guide and it seems to work. Great work on the CSS Variables, took a bit of trial and error, but works fine. Need to fine-tune our CI colors now.


@SM-26

Where is ".icons"

The icons specified for icon>logo are relative to the .icon directory in the theme:

Please take a look at my migration at https://github.com/retest/docs/tree/feature/mkdocs-material-v5

I specified theme and put them under theme/.icon/retest/logo.svg to be in sync with fontawesome and other icon packs

Edit: notice the . before .icons

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Mar 11, 2020

Note that icons can only be used as SVGs, as they are inlined into the HTML.

I specified theme and put them under theme/.icon/retest/logo.svg to be in sync with fontawesome and other icon packs

Ah, yes! So custom icons can be specified when using theme extension - I haven#t thought of that. We should document that!

@wilhelmer

This comment has been minimized.

Copy link
Contributor

@wilhelmer wilhelmer commented Mar 11, 2020

So there's theme.logo, which can only be set to your own custom-made logo (png, svg, whatever).

And there's theme.icon.logo, which can only be set to any of the icons bundled with the theme, e.g., material/cloud.

Is that correct? IMHO, that's a bit confusing ...

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Mar 11, 2020

The idea was no unify icon configuration, so that maybe later we can add more icons to the theme.icon namespace that can be configured. I understand that it may be confusing at first. What would be a better approach? From v4 to v5 it currently is:

  • theme.logo.icon -> theme.icon.logo
  • extra.repo_icon -> theme.icon.repo
@wilhelmer

This comment has been minimized.

Copy link
Contributor

@wilhelmer wilhelmer commented Mar 11, 2020

Maybe:

  • theme.logo.icon -> theme.icon.logo
  • extra.repo_icon -> theme.icon.repo
  • theme.logo -> theme.icon.custom_logo
@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Mar 11, 2020

theme.logo can be any file format

fkorotkov added a commit to cirruslabs/cirrus-ci-docs that referenced this issue Mar 11, 2020
@wilhelmer

This comment has been minimized.

Copy link
Contributor

@wilhelmer wilhelmer commented Mar 11, 2020

And everything in the theme.icon namespace should be SVG only? Is that a must?

If yes, I don't know 鈥 but the difference between theme.logo and theme.icon.logo isn't clear just by looking at the names. Maybe theme.logo -> theme.custom_logo? But the other .logo can be customized too, as we just learned ...

@diba1013

This comment has been minimized.

Copy link
Contributor

@diba1013 diba1013 commented Mar 11, 2020

I agree that there is an inconsistency between theme.logo and theme.icon.logo and I moved the logo to theme.icon.logo because it makes more sense to merge these into one namespace.

But I do not know the code behind that and if the svg locking was done for a reason (e.g. to inline the svgs directly into the html) because otherwise it would have been to complicated or would have resulted in ugly code (e.g. exist check of file, etc).

But the other .logo can be customized too, as we just learned ...

As to update the documentation, it would be helpful to update the documentation and to make it more clear to what I did. Because what I did鈥攊n retrospect鈥攕eems quite simple, but if you do not have an idea on what I did, it seems complicated.

To elaborate: My solution (I did not check this) works only, because I have an overwritten theme defined. theme.icon.logo looks relative to a specific .icons directory that is only available from the theme. Thus to define theme.icon.logo the way I did, you need to overwrite a theme which is a more advanced topic and may be overkill for many use cases. Whereas theme.logo does not care where the icon is placed and therefore a more straightforwards and simple solution.

@wilhelmer

This comment has been minimized.

Copy link
Contributor

@wilhelmer wilhelmer commented Mar 11, 2020

Different topic:

In the OP, you mention:

  • Improved extensible keyboard handling

Could you elaborate on that, maybe with an example on how to add custom keyboard shortcuts? And maybe also add that to the docs?

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Mar 11, 2020

The point is that theme.icon.logo is inlined and thus needs to be SVG whereas theme.logo is embedded as an img. Maybe we should clarify that in the docs. If somebody has an idea how we could better clarify it, I would be happy to merge PRs.

@facelessuser

This comment has been minimized.

Copy link
Contributor

@facelessuser facelessuser commented Apr 1, 2020

I'm fine with using actions when it is nice a solid and does exactly what I want, but when it doesn't, and it is pretty easy to just manually do it, I usually just do it myself.

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 1, 2020

@Andre601 from the docs:

When tabs are enabled, top-level sections will be rendered in an additional layer directly below the header. The navigation on the left side will only include the pages contained within the selected section. Furthermore, top-level pages defined inside your project's mkdocs.yml will be grouped under the first tab which will receive the title of the first page.

You can't put a single entry via mkdocs.yml, as all top-level entries will be grouped under the first tab. Maybe look at mkdocs.yml of the project itself, it should be clearer then:

mkdocs-material/mkdocs.yml

Lines 114 to 134 in 728fef6

nav:
- Material: index.md
- Getting started: getting-started.md
- Extensions:
- Admonition: extensions/admonition.md
- CodeHilite: extensions/codehilite.md
- Footnotes: extensions/footnotes.md
- Metadata: extensions/metadata.md
- Permalinks: extensions/permalinks.md
- PyMdown: extensions/pymdown.md
- Plugins:
- Minify HTML: plugins/minify-html.md
- Revision date: plugins/revision-date.md
- Search: plugins/search.md
- Specimen: specimen.md
- Customization: customization.md
- Compliance with GDPR: compliance.md
- Release notes: release-notes.md
- Author's notes: authors-notes.md
- Contributing: contributing.md
- License: license.md

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 1, 2020

So tl;dr it's not possible to have it as a separate tab at the top then. Got it.

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 1, 2020

You could always use theme extension and override partials/tabs.html if you'd like more control.

@fkorotkov

This comment has been minimized.

Copy link

@fkorotkov fkorotkov commented Apr 1, 2020

@Andre601 you can take a look at my solution for the issues that I dod for https://cirrus-ci.org to have single pages on top of the page. Here is nav-item partial you can take a look at.

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 1, 2020

I'm not really into implementing own HTML files, which is the entire reason I use MkDocs in the first place: To not have to deal with a lot of HTML, CSS and other configuration.
Thanks anyway for the example.

@fkorotkov

This comment has been minimized.

Copy link

@fkorotkov fkorotkov commented Apr 1, 2020

There are minor changes if you'll diff against the original nav-item. But yeah, I feel you 馃槄

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 1, 2020

A bit sad, that there isn't really a main chat for common mkdocs/material questions.
I know that there's a chat on gitter, but it's more about Material and not MkDocs according to the welcome message there, and Stackoverflow is way to unreliable and slow for some small, common questions.
I also don't want to annoy you guys here constantly with such unrelated questions (which also triggers notification for everyone watching this issue 馃憖)

@ofek

This comment has been minimized.

Copy link

@ofek ofek commented Apr 1, 2020

This looks promising zeit/now#3874

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 1, 2020

To not have to deal with a lot of HTML, CSS and other configuration.

Unfortunately, it鈥檚 impossible to provide a theme that fits everyone鈥檚 use case. I understand that you don鈥檛 want to go down that path, but you also have to understand that our time is limited, so we have to cut configuration at some point for customization. Funnily, the more configuration options this theme gets, the more users want even more options 馃槄

A bit sad, that there isn't really a main chat for common mkdocs/material questions.

I think the main problem is that something like this would result in endless requests for customizations, and I think nobody (including me) wants (and can) to do all of this for free.

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 1, 2020

I think the main problem is that something like this would result in endless requests for customizations, and I think nobody (including me) wants to do all of this for free.

I don't generally mean about new features here, but rather that there isn't a common chat/place where you could ask all kinds of questions, which aren't always about material or even MkDocs (e.g. how to implement something like netlifly to build previews from pull requests)

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 1, 2020

I think that's pretty much what StackOverflow is for. Additionally there might be Slack or Discord channels for this topic.

@wilhelmer

This comment has been minimized.

Copy link
Contributor

@wilhelmer wilhelmer commented Apr 2, 2020

I think it's probably safest to use RC3 for now, although it has some very minor bugs. Nevertheless, I think publishing something on April 1 is never a good idea 馃槈That's also why I moved the release date to April 7, as Tuesdays should be the best weekday for releases and March 31 might already be April 1 in some timezones.

We went live with RC4 yesterday! 馃嵕 https://docs.baslerweb.com

Good thing about launching on April 1st: If there are major bugs, you can always say haha first of April, was just a joke, we'll release the real version tomorrow ...

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 2, 2020

When trying out search tokenisation, I found I had to put the seaprator declaration in quotes
(per: https://deploy-preview-1486--mkdocs-material-preview.netlify.com/plugins/search/#tokenization )

like this

plugins:
  - search:
      separator: '[\s\-\.]+'

I got it working nicely here - thanks!: https://rohancragg.co.uk/

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 2, 2020

@rohancragg thanks for reporting! Fixed the docs in 2cc0685.

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 2, 2020

I found that I had to make the following change to my PIP requirements.txt:

pymdown-extensions>=7.0b2
mkdocs-material>=5.0.0rc4
@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 2, 2020

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 2, 2020

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

OK, thanks, it's probably just because I'd been specifying it and didn't need to

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 2, 2020

I had to remove the reference to - pymdownx.superfences in my mkdocs.yml

You might want to add that to the upgrade steps.

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 2, 2020

pymdownx.superfences should continue to work.

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 2, 2020

RC 4 has the correct version of Pymdown as a dependency, so no need to specify it. A compatible version is always included with the theme.

Good to know.

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 2, 2020

It's also mentioned in the new docs 鈥 I have removed all installation instructions for packages that are bundled anyway (even MkDocs!) 馃榾For Pymdown it makes sense to let the theme select the supported version. Also, @facelessuser, the author of Pymdown Extensions, is very responsive, so the package will almost likely almost be up-to-date.

@facelessuser

This comment has been minimized.

Copy link
Contributor

@facelessuser facelessuser commented Apr 2, 2020

yup, SuperFences 100% works. All of it works with Material, though not everything pymdown-extensions does is directly supported with styling, but most like 99%.

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 3, 2020

pymdownx.superfences should continue to work.

If I don't remove it get this warning on mkdocs build:

[~]\scoop\apps\python\3.8.2\lib\site-packages\pymdownx\superfences.py:634: PymdownxDeprecationWarning:
The tab option in SuperFences has been deprecated in favor of the general purpose 'pymdownx.tabbed' extension.
While you can continue to use this feature for now, it will be removed in the future.
Also be mindful of the class changes, if you require old style classes, please enable the 'legacy_tab_classes' option.

  warnings.warn(MSG_TAB_DEPRECATION, PymdownxDeprecationWarning)

is this perhaps because I've enabled this:

features:
    - tabs
    - instant
@facelessuser

This comment has been minimized.

Copy link
Contributor

@facelessuser facelessuser commented Apr 3, 2020

It says the [tab option] (https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#tabbed-fences) has been deprecated in SuperFences, not that SuperFences is deprecated. Moving forward, people should use the general Tabbed extension to do tabbed code, but during the transition period, you can still use SuperFences' tab option, but it'll warn you that one day it won't work, so it is probably better to use the general extension some time soon to prevent bring caught unawares.

@rohancragg

This comment has been minimized.

Copy link

@rohancragg rohancragg commented Apr 3, 2020

@facelessuser - thanks, yes, I've now removed all use of tabbed fences and the warning goes away!

@Andre601

This comment has been minimized.

Copy link

@Andre601 Andre601 commented Apr 3, 2020

Is it intentional, that Material Theme now omits the link to MkDocs rather than adding its own link to the footer? (made with <Material for MkDocs> instead of powered by <MkDocs> and <Material for MkDocs> (<> mean that those words have links))

Also, no expert on english grammar so perhaps a stupid question, but why is it lowercase at the beginning and not Uppercase (made/powered instead of Made/Powered)

@squidfunk

This comment has been minimized.

Copy link
Owner Author

@squidfunk squidfunk commented Apr 3, 2020

Yes. That's an intentional change. It reduces the clutter in the footer. Before, MkDocs was the first link, so people go to the MkDocs page with no Material theme whatsoever. Since Material "brings its own MkDocs" (as a requirement), there's no need to link to MkDocs itself. The docs now also don't include MkDocs installation instructions, as it's automatically installed with the theme.

Just trying to be less confusing.

I thought about making it uppercase, you're probably right.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
You can鈥檛 perform that action at this time.