search

squidfunk / mkdocs-material

Documentation that simply works
https://squidfunk.github.io/mkdocs-material/
MIT License
20.58k stars 3.51k forks source link

🚀 Material for MkDocs 5.0.0 RC 4 #1498

Closed squidfunk closed 4 years ago

squidfunk commented 4 years ago

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

Fixed in RC 2

Fixed in RC 3

Fixed in RC 4

Migration

See the migration guide in the deploy preview.

lazka commented 4 years ago

Using 5.0.0rc3 the build fails when using social links:

Traceback (most recent call last):
  File "/home/lazka/.local/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/home/lazka/.local/lib/python3.8/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/__main__.py", line 159, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 288, in build
    _build_theme_template(template, env, files, config, nav)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 114, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
  File "/home/lazka/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 93, in _build_template
    output = template.render(context)
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/environment.py", line 1090, in render
    self.environment.handle_exception()
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/environment.py", line 832, in handle_exception
    reraise(*rewrite_traceback_stack(source=source))
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/_compat.py", line 28, in reraise
    raise value.with_traceback(tb)
  File "/home/lazka/.local/lib/python3.8/site-packages/material/404.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/base.html", line 172, in top-level template code
    {% block footer %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/base.html", line 173, in block "footer"
    {% include "partials/footer.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/partials/footer.html", line 59, in top-level template code
    {% include "partials/social.html" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/material/partials/social.html", line 10, in top-level template code
    {% include ".icons/" ~ social.icon ~ ".svg" %}
  File "/home/lazka/.local/lib/python3.8/site-packages/jinja2/loaders.py", line 199, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: .icons/.svg

The error starts once I add the social config from the docs:

extra:
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://www.linkedin.com/in/squidfunk'
squidfunk commented 4 years ago

type was renamed to icon, as stated in the migration guide. The paths did also change. The OP contains the link to the migration guide.

lazka commented 4 years ago

Ah, thanks.

Andre601 commented 4 years ago

A suggestion for the icons section of the new guide: Maybe mention how the names of the different packs are? I mean you mention material and fontawesome, but what would be the "prefix" for octicons? Just octicons, or something else?

And not sure how important this would actually be for this theme, but perhaps mention that yiz can alter the edit-uri by providing edit_uri in the mkdocs.yml? I myself had a hard time finding this anywhere and only found it through luck... But I guess this is more the job of the actual mkdocs documentation? Nvm I'm actually blind

squidfunk commented 4 years ago

I‘m open to PRs improving the docs, especially on migration. It’s even better coming from actual users than me.

However, as you would have to look up the name of the icon anyway, my idea was that stating the name of the folder where those icons reside was probably enough. We can’t list all of the 5k icons, obviously.

Andre601 commented 4 years ago

We can’t list all of the 5k icons, obviously.

My point was, that it should at least mention the how I called it "prefix" (i.e. fontawesome) as it's not 100% sure for people where to look for the icons.

And a unrelated question, but still about the new theme version: Did something change in terms of custom CSS? It seems that the codehilite colours for code blocks no longer seems to apply properly as they did for the dark theme CSS I used with the stable release.

I use the dark Theme CSS file from henrywhitake3

Stable version: image

5.0.0 RC3 image

squidfunk commented 4 years ago

Unfortunately we cannot provide support for downstream projects. Some styling (i.e. selectors) changed for code highlighting, so yes, it might be related to that. It’s probably best to create an issue on the respective repository.

Andre601 commented 4 years ago

found the problem: codehilite changed to highlight it seems.

squidfunk commented 4 years ago

Both highlighting extensions are supported as in 4.x, so no change on that front. Depends on whether you use pymdownx.highlight or codehilite in mkdocs.yml.

Andre601 commented 4 years ago

I use the codehilite one, which makes this even more interesting/weird. I'll open an issue on the repo of the dark theme to suggest an alternative css file supporting the highlight option.

squidfunk commented 4 years ago

@facelessuser any ideas what could be causing this?

facelessuser commented 4 years ago

@squidfunk, just curious, I noticed that the included Material icons are a mix of official and contributed, I assume it from this collection: https://materialdesignicons.com/. I noticed that some icons have IDs attached to them, for instance I think some of the brand icons in Material (GitHub for instance). Depending on how they are inlined, it could much with other ids. When you insert them via Jinja, do you strip the IDs? I figure when they are set as background or mask-image it shouldn't be a problem. Just something I noticed and am curious about.

squidfunk commented 4 years ago

On a second note: one of the next minor version, most probably 5.1 will include a native dark mode.

squidfunk commented 4 years ago

@facelessuser the icons are extracted from the material-design-icons-svg package which seems to scrape the official site. I included the IDs at some point but removed that again from the Webpack copying logic.

facelessuser commented 4 years ago

@squidfunk @Andre601 SuperFences and InlineHilte use pymdownx.highlight to handle code highlighting, not Codehilite. For a long time they mirrored the settings if you were using CodeHilite, but it still always used pymdownx.highlight.

So in Material 4.X, if you used codehilite, pymdownx.highlgiht would copy over the class name used by codehilite, which is codehilite. But in Material 5.X (which uses pymdownx 7.0 prerelease) does not. pymdownx.highlight uses highlight by default, but you can configure it in pymdownx.highlight, it should work along side codehilite.

squidfunk commented 4 years ago

Thanks for the explanation!

facelessuser commented 4 years ago

@facelessuser the icons are extracted from the material-design-icons-svg package which seems to scrape the official site. I included the IDs at some point but removed that again from the Webpack copying logic.

Cool, so no IDs, good to know :+1:.

facelessuser commented 4 years ago

The big thing you gain from using CodeHilite is indented code block headers with shebangs, and markdown.extensions.fenced_code uses CodeHilite for its highlighting.

    #!python
    import sys

But if you are using pymdownx.superfences you don't really need it:

```python
import sys


I find no use for CodeHilite, so I no longer try to support anything related to it. I only mirrored the options for a while to transition away from using CodeHilite (which SuperFences used to use a long long time ago).
facelessuser commented 4 years ago

Last post I swear 🙂 . The super short answer:

The referenced dark theme only uses the class codehilite: https://github.com/henrywhitaker3/mkdocs-material-dark-theme/blob/master/site/assets/css/dark-theme-system.css#L153. So you need to use your own with updated classes (highlight) or force pymdownx.highlight to use the class name codehilite.

squidfunk commented 4 years ago

... or wait for 5.1, which should shortly follow after the initial release 😉 probably towards the end of April.

squidfunk commented 4 years ago

I decided to release a last release candidate, as there have been a lot of fixes lately. The final release date will be April 7.

wilhelmer commented 4 years ago

Printing is not working properly for me in Firefox v74.

Steps to reproduce:

  1. Set up a minimal project with one fairly long topic (>1 page when printed).
  2. Build.
  3. Open topic in Firefox 74.
  4. File > Print preview.

Result: The print preview shows only one page.

Expected result: The print preview should show all pages needed to print the topic.

Works in Chrome, but not in FF.

wilhelmer commented 4 years ago

Also, __material is no longer defined in RC4? Can't access it from the console either. Did I overlook that change?

squidfunk commented 4 years ago

__material was renamed to app. Does the print problem happen with Firefox and v4?

wilhelmer commented 4 years ago

Thanks. No, does not happen with FF and v4.

squidfunk commented 4 years ago

Confirmed. Could you create a new issue (or PR?)? I guess it has to do with overflow: hidden and flex which should be easy to remove for print styles on body.

https://bugzilla.mozilla.org/show_bug.cgi?id=258397, respectively https://bugzilla.mozilla.org/show_bug.cgi?id=521204

lazka commented 4 years ago

Instant loading bug (Firefox and Chromium):

squidfunk commented 4 years ago

@lazka thanks for reporting! Could you create a new issue, so we can keep track?

jaimeiniesta commented 4 years ago

Awesome! Just deployed our docs and no html/a11y issues were detected this time - except for the muted ones we already discussed. 💪

Andre601 commented 4 years ago

I'm not entirely sure if this would be for here, or is better suited for a markdown-expansion like the ones of pymdown, but how about a implementation, to easy add any icon of material, fontawesome or github? I like that you can use them for social links and other specific places, but I think me and other people would love it, if there was a way to directly put those icons into the text, without requiring this entire <i class="blablabla"> html stuff (keep it very "markdown like" if you will)

A syntax I think would be an idea is perhaps -prefix:icon-? Like I said, not sure if this is best suited here or better of for a markdown-extension.

facelessuser commented 4 years ago

@Andre601 some ideas for this are already being floated: https://github.com/squidfunk/mkdocs-material/pull/1475.

Andre601 commented 4 years ago

A bit unrelated question, but would I just need to use this part here if I want to make a GitHub Action automatically update a page, when a PR was merged on the repo containing the docs? I am aware that there is a GitHub Action more or less suited for this, but I'm quite sure it doesn't use Material 5.0.0 RC4 and perhaps won't even really support the PyMdown 7 extensions....

squidfunk commented 4 years ago

You could use the workflow as a starting point. From what I read from the MkDocs action, however, it seems to assume a requirements.txt file that is installed, so you could probably specify the versions you want. Haven't tested it, though.

Andre601 commented 4 years ago

Is there any way I can force MkDocs/Material to put a single entry in the nav-list to the tabs at the top? When I f.e. only have - Contribute: contribute.md does it not work. When I, however, set the following does it work (But it is a bit annoying)

nav:
- Contributing:
  - Contributing: contribute.md
facelessuser commented 4 years ago

I also deploy docs with just this: https://github.com/facelessuser/pymdown-extensions/blob/master/.github/workflows/deploy.yml#L10. I found it just easier to manually do it. Granted, I didn't need all the matrix stuff as I'm only running it on one Python, but I copied and pasted it from other workflows I was doing, so 🤷‍♂ .

ofek commented 4 years ago

Yeah we're doing it manually too https://github.com/DataDog/integrations-core/blob/hack-a-doc/datadog_checks_dev/datadog_checks/dev/tooling/commands/docs/push.py

facelessuser commented 4 years ago

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 commented 4 years ago

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

https://github.com/squidfunk/mkdocs-material/blob/728fef6ec8259e910500885047911c18bae145da/mkdocs.yml#L114-L134

Andre601 commented 4 years ago

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

squidfunk commented 4 years ago

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

fkorotkov commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

Andre601 commented 4 years ago

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 commented 4 years ago

This looks promising https://github.com/zeit/now/discussions/3874

squidfunk commented 4 years ago

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

Unfortunately, it’s impossible to provide a theme that fits everyone’s use case. I understand that you don’t 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 commented 4 years ago

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 commented 4 years ago

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

wilhelmer commented 4 years ago

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 commented 4 years ago

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/