🚀 Material for MkDocs 8 – Beta

[squidfunk]

With the help of my awesome sponsors, I'm happy to announce that the 'Ghost Pepper' funding goal has been reached, which means that code annotations, anchor tracking and versioning warnings are finding their way into this repository!

Since those are some pretty nifty features, it's a good time to wrap them up into a new major release and drop some long-standing deprecated features. This issue will track the progress on the road from the beta to the final release of version 8.

If you experience any problems, for now, please report them as a comment in this issue.

Installation

pip install mkdocs-material==8.0.0b2

Note that this is a beta release.

Changes

Added

• Code annotations: this is probably the most anticipated new feature. After finishing the merge and deprecations, I'll revisit the placement issues on mobile. Those need to get fixed before we push out the major release.

• Version warning and Anchor tracking

Improved

• Content partials: there's now a new partial, which allows fpr customizing the appearance of the Markdown content without overriding base.html. This makes it easy to add a further button to the top of a page or to add arbitrary content to the footer of a page:

  {% block content %}
    {% include "partials/content.html" %}
  {% endblock %}

• Copyright partial: the copyright has been moved into a separate partial, which lifts the need to override the footer.html template when changing the copyright information.

  <div class="md-footer-meta md-typeset">
    <div class="md-footer-meta__inner md-grid">
      {% include "partials/copyright.html" %}
  
      <!-- Social links -->
      {% if config.extra.social %}
        {% include "partials/social.html" %}
      {% endif %}
    </div>
  </div>

• Details: the open/closed state of details elements is now preserved when exiting print mode. Prior, details elements were always opened and left open when exiting print mode. Now, they will always return to their prior state.

• Fonts: The CSS variables for fonts which are set via mkdocs.yml have been renamed, and are amended with fallback fonts by the theme, so they can be set on arbitrary elements. Before, the fallback fonts had to be copied in order to override fonts on a nested element.

Removed

• Tabbed (legacy): from version 8, only the alternate_styleof the Tabbed extension is supported, and thus mandatory. The alternate implementation is superior in many ways, and there's no reason for us to keep the legacy implementation, as it just blows up the size of the CSS.

• Disqus: sadly, Disqus free version has become so horrible with advertisements before and after the comment section, which is why I don't want to endorse its usage anymore. Disqus was added at a point in time where its free version was pretty good. This is not the case anymore. However, there's a new page-footer.html partial that makes it pretty easy to add it back through customization. The new comment system guide still uses Disqus as an example for a custom integration until we found a new, better provider. Suggestions welcome.

• extra.manifest: the web app manifest configuration setting was removed because it is essentially just a single meta tag that links to a file that must be provided by the author. Use theme extension and add it to extrahead.

• extracopyright: the extracopyright variable allows to set a variable via customization that was added after the copyright information. Since the copyright information is now encapsulated in a separate partial, overriding the partial is more flexible. We don't want to provide redundant ways of achieving the same thing.

• seealso: the seealso qualifier was originally adapted from the readthedocs theme, in order to make it easier for authors to migrate to Material for MkDocs. However, when the title is omitted, the admonition extension will render it as Seealso, which is incorrect English.

• site_keywords: this was added in a PR and I failed to check if this was actually supported by MkDocs. It isn't. In fact, MkDocs will print a warning that this is an unsupported setting. For this reason, we'll remove it because it only leads to confusion.

• prebuild_index: previously deprecated, support was now removed. See linked issue (bottom).

TODO

• Fix positioning issues for code annotations
• Skip empty p elements before code annotation list
• Close code annotation when bubble is clicked again
• Update documentation for Tabbed
• Update documentation for adding back Disqus via customization
• Update upgrade guide

---

• Material for MkDocs 8 #3218
• [insiders] Code block annotation alignment for comment lines #3145
• Intent to deprecate: prebuilt search index #2976
• Code block annotations are misaligned on mobile #2475

[Andre601]

Would you be willing to consider implementing native support for other (open-source) discussion systems such as giscus?

[facelessuser]

Ugh, https://github.com/facelessuser/mkdocs-material-extensions breaks with beta versioning 😢. I guess I need to fix that as it makes it hard to test the beta.

    M_VER = tuple(int(x) for x in pkg_resources.require('mkdocs-material')[0].version.split('.')[:3])
ValueError: invalid literal for int() with base 10: '0b1'

[facelessuser]

Never mind, I was on an old local version 🤦🏻

[facelessuser]

Testing seems to indicate everything is working as intended (at least for me). Interested in finally playing code annotations now they are coming to the public distribution (never got around to playing with them in insiders 🙃).

[squidfunk]

Would you be willing to consider implementing native support for other (open-source) discussion systems such as giscus?

I'm not sure. I'm thinking of leaving the discussion system implementation as an exercise to the author. I mean, it's absolutely trivial now that there is page-footer.html, but we could definitely switch the documentation to a setup guide for giscus.

Update: the partial is now called content.html, see the latest update to the OP.

[squidfunk]

Update: I've made some good progress today, but code annotations still suffer from the issues reported in #2475 on mobile. However, since after fixing #3145 we can now place code annotations anywhere in the comment and they're not eaten up, I had some other problems to solve, namely that code annotations are always exactly as wide as the references from which they're generated. I have a working copy, which still needs some polishing, but I'm quite happy with the result. The following screenshot shows that the text after the code annotation lines up perfectly with a non-code-annotation line:

This is a minor, but pretty important detail, because it means that the code is formatted exactly as before.

[Andre601]

So, I want to try this out with my docs, because the annotation thing sure could be helpful with the API docs I have.
Question now is, would I need to update anything specific (i.e. pymdownx or the emoji extension) to properly work with this beta build?

[facelessuser]

It sounds like only Tabbed should be updated to use new alternate format. That is what I saw from my brief testing.

[squidfunk]

Correct, Tabbed needs to be set to:

markdown_extensions:
  - pymdownx.tabbed:
      alternate_style: true 

Other than that, if you have customization, some of those might break. I need to find the time to write an upgrade guide, but it's actually not that much for most users, because mostly new partials have been introduced. Some config settings were removed, though (see OP). Please feel free to document any roadblocks you're running into in this thread!

[Andre601]

I either do something wrong or either Pymdownx's Highlight or Material for MkDocs doesn't support json5 as a supported syntax for the annotations.

Does Material for MkDocs download Pygments or will a manual download be required for it?

[squidfunk]

So first, there doesn't seem to be a JSON5 lexer. Second, JSON doesn't support comments. For now, you can use the js lexer, which looks almost the same as JSON and supports both // ...and /* ... */ comments. Pygments syntax highlighting is required. This is also mentioned in the documentation.

In the future, there will be an alternate syntax to add code annotations to any line, regardless of language. The limitation will be that they can only be added at the end, which should however work for most use cases.

Does Material for MkDocs download Pygments or will a manual download be required for it?

Pygments is automatically installed and enabled when you use pymdownx.highlight, unless explicitly disabled.

[Andre601]

So first, there doesn't seem to be a JSON5 lexer. Second, JSON doesn't support comments. For now, you can use the js lexer, which looks almost the same as JSON and supports both // ...and /* ... */ comments. Pygments syntax highlighting is required. This is also mentioned in the documentation.

In the future, there will be an alternate syntax to add code annotations to any line, regardless of language. The limitation will be that they can only be added at the end, which should however work for most use cases.

Does Material for MkDocs download Pygments or will a manual download be required for it?

Pygments is automatically installed and enabled when you use pymdownx.highlight, unless explicitly disabled.

Json5 is a thing... It is precisely for comment support.

Missunderstood the sentence... Kinda sad

[facelessuser]

pymdownx.highlight just uses whatever Pygments provides and whatever 3rd party Pygment's lexers you've installed. I'm sure you could probably subclass the JSON lexer and create a JSON5 version. I realize it isn't trivial though. Personally, using JS is usually sufficient.

[corykinney]

Not sure if this deserves its own issue, since I don't remember it happening before the beta for version 8 started, but the mermaid.js diagram examples are showing up as normal code blocks on the documentation page for me.

On a different note, and this is just a personal opinion, I think it might be more intuitive if code annotation bubbles acted as a toggle, where you could click to open and click to close, rather than having to click elsewhere on the page (although I think that should remain).

[squidfunk]

Mermaid integration is still exclusively in Insiders 😉 It will be released here when the next funding goal is hit.

On a different note, and this is just a personal opinion, I think it might be more intuitive if code annotation bubbles acted as a toggle, where you could click to open and click to close, rather than having to click elsewhere on the page (although I think that should remain).

I'd be interested to hear other user's opinions on this. Personally I find it pretty intuitive, but I'm willing to discuss.

[corykinney]

Mermaid integration is still exclusively in Insiders 😉 It will be released here when the next funding goal is hit.

Yes, and I am looking forward to that so I can use it! But when I visit your live documentation, for each diagram type, it has an Example block and a Result block. Isn't the Result supposed to show the actual diagram that would be rendered?

[squidfunk]

Ah, interesting! Yes, that's definitely an error, but it's not related to version 8. I'll look into that.

[Andre601]

So first, there doesn't seem to be a JSON5 lexer. Second, JSON doesn't support comments. For now, you can use the js lexer, which looks almost the same as JSON and supports both // ...and /* ... */ comments. Pygments syntax highlighting is required. This is also mentioned in the documentation.

In the future, there will be an alternate syntax to add code annotations to any line, regardless of language. The limitation will be that they can only be added at the end, which should however work for most use cases.

Does Material for MkDocs download Pygments or will a manual download be required for it?

Pygments is automatically installed and enabled when you use pymdownx.highlight, unless explicitly disabled.

Sadly doesn't work...
The highlighting works, but the annotations aren't recognized or rendered... Could it be because I set a custom title?

[squidfunk]

@corykinney fixed, that was just stale configuration!

[squidfunk]

@Andre601 no, it should work despite the custom title. Could you provide the Markdown please? Also, did you enable the content.code.annotate feature flag?

[Andre601]

@Andre601 no, it should work despite the custom title. Could you provide the Markdown please? Also, did you enable the content.code.annotate feature flag?

Here's a gist of the file: https://gist.github.com/Andre601/df9bbd4cf35247cee7cd051aff6414c9
And yes, the feature flag is enabled. You can find current configuration on this repo's branch: https://github.com/purrbot-site/Docs/tree/feature/use-material-v8

[squidfunk]

The indentation is incorrect – the list is outside of the tab, you must indent the list so that it matches the code block indent. Your list is currently not coming next, after the code block, but after the tab. This:

=== "Body"
    ```js title="JSON Body Example"
    ...
    ```

1.  Foo

Must be:

=== "Body"
    ```js title="JSON Body Example"
    ...
    ```

    1.  Foo

[Andre601]

The indentation is incorrect – the list is outside of the tab, you must indent the list so that it matches the code block indent. Your list is currently not coming next, after the code block, but after the tab. This:

=== "Body"
    ```js title="JSON Body Example"
    ...
    ```

1.  Foo

Must be:

=== "Body"
    ```js title="JSON Body Example"
    ...
    ```

    1.  Foo

....that's a typical andre moment... 🤦

[Andre601]

One other question.

Will later sections require a continued nummeration or could I repeat 1, 2, etc.?

Like would it need to be:

```js
{
  "text": "text" // (1)
```

1.  Text

```js
{
  "text": "text" // (2)
```

2.  More text

or would this work?

```js
{
  "text": "text" // (1)
```

1.  Text

```js
{
  "text": "text" // (1)
```

1.  More text

I'm not sure since the docs only use one text example which doesn't make it clear...

[squidfunk]

The numbers are per-code block. The reason for this is that Markdown lists will always restart, so even though you may number your Markdown list 4., 5., 6., ... it will be converted to li elements which are implicitly numbers through CSS, always converted to 1., 2., 3., ... Thus, the only option is to always start annotations from 1.

[johnthagen]

Just an idea, but would it be possible to make it so that when you press the "Copy to clipboard" button for a code block that used annotations that the # before the annotation wasn't copied?

The new annotations look great, but it seems like a downside is they clutter copied commands (e.g. when using with bash highlighting) with extra comment characters.

Consider a bash block like:

command \
   --argument1 \ # (1)
   --argument2 \

When the user copies this, the second \ won't be used properly when its pasted into a terminal.

[squidfunk]

@johnthagen the problem is that it's not really decidable what of a comment should be copied and what not, e.g.:

const foo // this is a (1) comment

I think it's better to replace annotations with their textual counter part, e.g. (1) when copying, so it's consistent. Note that the preserving of comments is new behavior that was introduced in #3145. I'm thinking of an alternate syntax that allows to revert back to the old behavior, stripping the entire block. Maybe something like (1)!.

[johnthagen]

I'm thinking of an alternate syntax that allows to revert back to the old behavior, stripping the entire block.

That sounds great to me.

[whentojump]

Many thanks to all contributors for your great efforts!

Everything turns out great. Just want to share my strugglling during the past hour: I'm not sure whether I will be the only silly, poor guy to do so. 🤣

I recoganized the important - content.code.annotate configuration snippet as just a demonstration of whatever code, since itself uses code annotation. So I skipped it every time as I read through the documentation trying to figure out why my annotation was not working.

[squidfunk]

@Wen-Tao-Zhang hmm, the documentation states that it must be enabled in mkdocs.yml, doesn't it? Excerpt:

Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block. Add the following to mkdocs.yml to enable them globally:

Any idea how we could further improve this?

[whentojump]

Any idea how we could further improve this?

I was not suggesting that. The documentation is good and I did find the statement at last. I just somehow got stuck because I skimmed through the documentation over and over carelessly. My post was just a reminder for someone like me (if there's any) 🤣.

Thank you for your quick reply!

[corykinney]

I'd be interested to hear other user's opinions on this. Personally I find it pretty intuitive, but I'm willing to discuss.

Late response, but just wanted to clarify that I wasn't suggesting removing clicking outside of the annotation to close it, but that clicking the bubble should also close the annotation.

[julienlavergne]

Just an idea, but would it be possible to make it so that when you press the "Copy to clipboard" button for a code block that used annotations that the # before the annotation wasn't copied?

The new annotations look great, but it seems like a downside is they clutter copied commands (e.g. when using with bash highlighting) with extra comment characters.

Consider a bash block like:

command \
   --argument1 \ # (1)
   --argument2 \

When the user copies this, the second \ won't be used properly when its pasted into a terminal.

Also interested in this. It would be consistent with other features that "augment" the block without having to touch the content, like syntax coloring and line highlight.

And it would also open the door in having annotation working with snippets and, overall, blocks that do not easily supports comments.

Since the list following the block already get a special treatment, I rather specify the line and column where I want the annotation to appear there, instead of inline in the block.

[ofek]

Great work 💯

FYI, we are also extremely interested in code annotations not interfering with copying.

[whentojump]

Consider a bash block like:

command \
   --argument1 \ # (1)
   --argument2 \

When the user copies this, the second \ won't be used properly when its pasted into a terminal.

FWIW, I recently came across a page (and its source) with code blocks like this, who seems to use AsciiDoc. Not sure how/whether they handle the issue mentioned here by the author.

[squidfunk]

FYI, we are also extremely interested in code annotations not interfering with copying.

@ofek Thanks for the feedback! Code annotations do not interfere with copying – they are not marked with user-select: none, so the actual content is not included. They are also stripped when using the copy-to-clipboard button. However, the comment where they are placed is, so I guess you're seconding this idea?

[squidfunk]

I'm very grateful for the feedback! Just to be clear what the rationale behind the current implementation is:

It would be consistent with other features that "augment" the block without having to touch the content, like syntax coloring and line highlight.

This is in fact exactly what code annotations do – they just replace markers in comments – nothing more. This means that a valid code snippet will remain valid, but invalid code snippets are not corrected to be valid. Let's take the example that was posted earlier again:

command \
   --argument1 \ # (1)
   --argument2 \

This example is invalid, because comments are not allowed in this position. This means that it's (currently) not possible to add a code annotation on this line, same as it's not possible to add a comment in the underlying language. So yes, we could add an alternate syntax that says "strip the entire comment and inline the annotation", but this means that the code example would render as invalid code in the following cases:

1. JavaScript is not available: slow connections, JavaScript turned off, whatever – code annotations will currently gracefully fallback to a Markdown block with your original comments, i.e. (1), (2), + a list below it. This was a deliberate decision because it's a design principle that Material for MkDocs follows – always work without JavaScript. Of course, features as search are not possible to implement without JavaScript, but in general, the site is perfectly usable.

2. Printing annotations: printing annotations is basically the same as "no JavaScript", because now code annotations are shown in their original form – a list below a Markdown block because that's the only way to support non-interactive mediums. Again, the code block would be invalid.

Nonetheless, I'm considering adding the stripping mode, but I have to work out the details for that. I want to revisit this topic together with placing annotations in languages that don't support comments because both problems are closely related. This is, however, something that can't be part of the 8.x release, because it's a whole other rabbit hole to go down. For this reason, please understand that code annotations are currently only valid in comments, which is stated in the documentation.

[squidfunk]

8.0.0b2 is out! This was really tough. Release notes:

• Switched to :is() selector for simple selector lists (main.css drops from 18kb to 16kb gzipped)
• Switched autoprefixer from last 4 years to last 2 years
• Fixed code annotations not scrolling on overflowing code blocks
• Fixed code annotations rendered too narrow on mobile
• Fixed code annotations overflowing on mobile
• Fixed code annotations not mounted due to empty p tags
• Fixed code after code annotations not aligning with grid
• Fixed if search is blank, page rendered improperly #3214

Again, feedback appreciated. The current iteration plan is to fix some outstanding issues and do some refactoring in the coming weeks, and then push out a final RC. I'm sorry that the way to a stable release is a little longer this time, but it will be worth it. Smaller footprint, some long overdue refactorings, and awesome new features.

[timvink]

Excited about this one!

Would v8 also be the right release to deprecate source-date.html partial, in favor of source-file.html ? See

mkdocs-material/src/partials/source-date.html

Lines 23 to 24 in 409d151

	<!-- Kept for backward compatibility. This file wil be removed in v8 -->
	{% include "partials/source-file.html" %}

I'd need to fix a plugin as well (timvink/mkdocs-git-revision-date-localized-plugin#53)

[squidfunk]

Yep, I've already removed the partial and everything that was linked to it.

[jrappen]

@squidfunk You might want to mention the new copyright partial on ./setup/setting-up-the-footer/#copyright-notice.

[squidfunk]

I've finished work on the v8 branch and just merged it into master. I'll add the missing pieces to the documentation and will issue a release. Many thanks to all who took part in the beta. Since there was not much feedback on the betas, I decided to skip the RCs and just get it out the door.

[squidfunk]

8.0.0 was just released. Please report any issues encountered as usual (and not here).

[Andre601]

Nice work.

One thing tho: Looking at the Adding a comment system page, do I feel like it kinda favours Disqus a bit too much and goes more into "How to setup Disqus" rather than "How to setup any Javascript-based comment system".

I feel like the page should be made a bit more generic and at most mention stuff you have to add alongside the basics to support Disqus.

Like from my basic JS knowledge and stuff do solutions like Giscus not need that first time setup to function.

I can offer to try and redo the page a bit, but currently thinking what the best wording would be to do this...

[squidfunk]

I already said in another comment that I'm happy to switch to another comment system provider or provide docs for multiple providers. Happy to collaborate on a PR, as from my viewpoint this is not a priority. Any help is appreciated.

Note that the generic part boils down to "extend the template and add what the provider gave you".

[squidfunk]

Oh, an @corykinney – thanks for the idea for closing open annotations on a subsequent click on the index. This is also included in the latest release. It's really a great idea.

[corykinney]

@squidfunk of course! Thanks for implementing it and offering so many awesome features in the free version!

[squidfunk]

As wished in #3219 (comment), the latest commit on the Insiders repository adds the ability to add an ! to a code annotation, which will replace the entire comment, stripping any control characters. This is the first extension towards code annotations in languages that don't support comments. More is about to come.

Markdown

``` sh
pip install \
  mkdocs-material \
  mkdocs-awesome-pages-plugin \ # (1)!
  ...
```

1. Complete replacement

Result

I'll wrap this up, add documentation and tie it to a funding goal when it will be released.

[squidfunk]

The changes were released as part of 8.1.0+insiders-4.4.0, which also adds the ability to directly link to code annotations. See a demo here: https://twitter.com/squidfunk/status/1469245481255673857