Source tags rendering incorrectly.

[tomchristie]

Refs: encode/django-rest-framework#5945

Building against 0.17.3

Building against 0.16.3

Presumably they're incorrectly being treated as a list even in the single-tag case.

[waylan]

This appears to be related to your custom theme and a change in how MkDocs handles Markdown meta-data. Markdown's default is to return raw meta-data such that each value is a list of lines (most of which contain one item). As this doesn't really make sense for MkDocs, in 0.17 MkDocs now joins those items into a string.

However, in your template, you are still treating the value of page.meta.source as a list, iterating over it, and creating a link for each item. Of course, this is creating a separate link for each character in the string. Instead, your template should just create a single link without iteration.

I'm assuming a page would only ever have a single "source" to link to, so the loss of ability to define a list shouldn't be a problem here. The change was made with the understanding that the feature was completely undocumented and mostly unused. @tomchristie I suspect you are the only one who has ever made use of it. The only officially supported meta-data key is template, which MkDocs was already joining into a single string. But even that was completely undocumented until after the change.

[tomchristie]

I suspect you are the only one who has ever made use of it.

This is very possibly true. 😝

[tomchristie]

I'm assuming a page would only ever have a single "source" to link to, so the loss of ability to define a list shouldn't be a problem here.

That’s not quite the case for us, no. Occasionally a single docs page will refer to more than one module.

[waylan]

Occasionally a single docs page will refer to more than one module.

I'm not quite sure of the best way to support this. The underlying library offers a way to define a "type" for a given key which would convert the raw data to that "type". However, that is not exposed to the MkDocs user.

Truth be told, I would like to switch to using YAML for the meta-data. Of course, YAML has type-support builtin and users already are using YAML for the config file. The problem is that Markdown systems which use YAML traditionally require a YAML deliminator (line of ---) to separate the data from the Markdown text. Therefore, it's not a straightforward switch. Users would need to edit their docs to conform to the new format. And a list would be defined differently as well, requiring an additional edit by users.

[mitya57]

However, in your template, you are still treating the value of page.meta.source as a list, iterating over it, and creating a link for each item. Of course, this is creating a separate link for each character in the string. Instead, your template should just create a single link without iteration.

I have just stumbled upon this. But the mkdocs’ documentation suggests that page.meta.source is a list, while it actually isn’t. Quoting the example from the documentation:

{% for filename in page.meta.source %}
  <a class="github" href="https://github.com/.../{{ filename }}">
    <span class="label label-info">{{ filename }}</span>
  </a>
{% endfor %}

Maybe that example should be fixed to replace the {% for %} loop with {% if page.meta.source %}?

Ah, and also the default theme is doing the same. I tried adding a source: line to a file in mkdocs’ own documentation, and it is rendered as a set of single letters.

[waylan]

Good catch. I wasn't aware we were expecting lists anywhere internally.

Probably the correct change to the documentation is to update the meta-data in the sample document to use YAML style meta-data. Then the existing template would be correct. Note that the existing behavior of Meta-Data is correctly documented under writing your docs (YAML style retains types, including lists, while MultiMarkdown style returns a single string for each key).

It might also make sense to have the templates check the type of page.meta.source and act accordingly.

[pawamoy]

So it seems like it's a limitation of MultiMarkdown which doesn't support list of strings? Do we know how widely used MultiMarkdown is? Should we deprecate it in favor of the probably more robust and common YAML front-matter metadata? @tomchristie I'd suggest we close this as out of scope. Are you still interested in this?

[tomchristie]

Are you still interested in this?

Let's close this as stale.