themes/mkdocs: Avoid inline ressources (like CSS and JS)

[nbraud]

This moves inline resources, like CSS and JS snippets, to base.{css,js}.

Inline resources make it impossible to implement a safe Content Security Policy, as they require using the 'unsafe-inline' directive, essentially voiding all guarantees CSP can provide.

With the suggested changes, the theme functions with the following policy:

Content-Security-Policy:
  default-src 'none'; connect-src 'self'; font-src 'self'; img-src 'self' data:;
  script-src 'self' https://cdnjs.cloudflare.com/ajax/libs/highlight.js/;
  style-src  'self' https://cdnjs.cloudflare.com/ajax/libs/highlight.js/;

[nbraud]

There is a preview version of those changes, with the CSP mentionned.

[waylan]

I don't have any objections to these changes. However, I feel the need to provide a warning regarding the Content Security Policy this allegedly enables. As a reminder, it is common for raw HTML within Markdown to make use of inline styles. In fact, this is even encouraged in Markdown's documentation.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself.

However, even with raw HTML disabled, many possible XSS vulnerabilities exist in Markdown's syntax. See Markdown and XSS for a great summary of those issues. In other words, updating the theme does not guarantee that the Content Security Policy is being met.

Of course, there will be some users of MkDocs who will want/need a strict Content Security Policy and without these changes they cannot have that (thus the changes will be accepted). This is just a warning that changing the theme alone is not going to guarantee such a policy is met. If users want to enforce such a policy for their Markdown, then they will need to take additional steps. That could be as simple as documenting and enforcing a strict policy of what is and is not allowed in the Markdown for their project. Or it could involve using a Plugin to run Markdown's output through an HTML sanitizer (presumably from the on_page_content event). Either way, those are things which can be implemented/enforced by the user and do not require any additional changes to MkDocs itself.

However, there are a couple additions we might want to consider:

1. The readthedocs theme should also be updated to meet the CSP (unless it already does -- I haven't checked).
2. We should add a comment to the release notes which notes that the existing themes now meet the CSP.
3. We might also want to add a note to the Contributing Guide which outlines a policy in which all contributions to MkDocs itself must meet the CSP so that users of MkDocs can generate sites which meet the CSP if they desire/need.
4. We might also want to consider what policy to adopt for our own documentation at mkdocs.org and document that as well.

[waylan]

To be clear, at a minimum, the first two items of the list in my previous comment (update the readthedocs theme and the release notes) are required before this PR can be accepted. Ideally, item 3 would be included as well, although this is not necessary. However, without it, we can't guarantee that future submissions won't undo the changes made here. Item 4 probably should be addressed separately.

[coliff]

This is a class so is missing the . at the beginning.

[coliff]

not a really big deal - but a class name of text-center would be more semantically correct.

[pawamoy]

Hi @nbraud, still interested in getting this merged? If so, could you rebase your code on master, and keep the PR related to how resources are loaded, without changing the actual CSS?