mkdocs: Static resources (especially CSS/JS!) shouldn't be automatically included

(Pulling this out from #972.)

Currently, MkDocs automatically includes all static resources from the docs dir in a build. This can cause issues if some files aren’t meant to be included but are located in the docs dir. For example, this could happen with files that get preprocessed by another tool into .md files for MkDocs (which was how I planned on doing auto-generation of docs from code for MkDocs if I ever get around to it).

However, there’s a more-significant issue: all CSS and JS files are automatically included in the generated HTML itself (except when hosting on RTD, apparently). This means that any CSS/JS used for static HTML files will get erroneously included in the MkDocs-generated HTML by default. The inconsistency with RTD adds another wrinkle to this. I think the behavior should be the same no matter what, and as Python says, “Explicit is better than implicit.”

At minimum, I think CSS and JS shouldn’t be automatically added to the generated HTML, but I’d prefer to see MkDocs only include files that are explicitly listed in mkdocs.yml. Doing so would make things more flexible when people want to do unusual things with MkDocs, and with globbing or the ability to include whole subdirectories of static resources, the configuration wouldn’t be much more complex than it is now.

About this issue

Original URL
State: closed
Created 8 years ago
Comments: 16 (16 by maintainers)

Commits related to this issue

Start the deprecation of auto-populating extra_css and extra_javascript See #986 — committed to d0ugal/mkdocs by d0ugal 8 years ago
Start the deprecation of auto-populating extra_css and extra_javascript See #986 — committed to waylan/mkdocs by d0ugal 8 years ago

Most upvoted comments

For what it’s worth, I use the extra_css to add a few minor styling things that I reference in Markdown via the Attributes extension. It looks like I could do this via customizing the styles block in the theme, but that’s a bit more work since I think I’d have to copy over all the default style tags into my override. The extra_css is nice since it’s a low-friction way of adding a few custom rules to every file.

One way of handling ignored files would be to pick a reasonable default for static files to include (maybe everything that doesn’t start with a dot?), but allow users to override this behavior by passing a set of files/globs to include/exclude. For instance:

static_resources:
  - include:
    - sample.txt
    - images/*.png
  - exclude:
    - _*

This would make it possible for people to pick what gets included or not while still retaining the default behavior of including everything. I would strongly prefer it if files were only included if you explicitly listed them, but this would be an ok compromise. In any case, the current strategy of automatically adding all CSS/JS files to the theme seems a bit too error-prone to me.

I’d also encourage a way of warning users if MkDocs is including files in the build that aren’t explicitly referenced in mkdocs.yml. This doesn’t have to be on by default, though. It could be part of a “strict” mode in MkDocs to help prevent mistakes when building your docs. I know I’d enable that for all my docs builds (but then, I’m the sort of person who always compiles with -Wall -Wextra -Werror -pedantic in GCC).

jimporter on Jun 30, 2016