-
-
Notifications
You must be signed in to change notification settings - Fork 2.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Static resources (especially CSS/JS!) shouldn't be automatically included #986
Comments
I have to admit that I have always found the the I'm guessing the answer is historical reasons. My assumption is that the "extra" settings were added first and the Suppose for a moment that I wanted to host a JavaScript file on my site for my readers to download as a separate JavaScript file. For the sake of argument, suppose I have a good reason for this file not being hosted elsewhere (such as a git repo). My first inclination would be to just include it next to my Markdown file which describes and links to it--the same way an image or PDF would work. But instead, the file gets added to I see two possible solutions:
Both solution's are backward incompatible for any user who relies on these settings being auto-populated. Personally, if we are going to make a change, I would suggest going all the way with option 2. And now is the time to do it as we approach version 1.0. For completeness, I should mention that some other static site generators have solved this type of problem by using a naming convention for "ignored" files. For example, any file or directory with a name that starts with an underscore is ignored. The settings file, the |
For what it's worth, I use the 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 |
RTD adds their own layer of restrictions by overwriting settings and they add theme customisations. We can't really control what they do with MkDocs. |
All you need to do is create a CSS file in your Although, in retrospect, it wouldn't get linked from the HTML. But you can use a Super Block to avoid replicating the entire
We should probably add that to the documentation somewhere. Granted, that is more involved than adding an item to the |
I'm not sure, I think it was this way when I first got involved in the project.
I think this is the option I would choose. Removing the option entirely makes adding small tweaks quite a bit harder - as you then need a |
We already skip any files starting with |
I can live with that. This issue has been bothering me from the beginning and I've been able to manage without saying anything so far. I just don't have to use it myself. |
I think we are really talking about two things again - but this time they are probably related enough to be in the same issue.
|
Yeah, I'm happy to compromise and leave (2) as it currently is so long as (1) gets fixed. However, I personally prefer being very explicit about what gets included in my docs, so I'd certainly be happy to see (2) fixed as well. That said, I don't have any current need for (2), so it's really just an academic question for me right now. |
It's interesting to note, that many people are already specifying the files. This may be due to the difference on RTD. Unfortunately there isn't an easy way to search for users that are using it implicitly. |
I always forget about that. I wonder if people who really want their
I agree here. |
This is basically how I feel about it. If we can come up with a compelling use-case then I would be more interested in the effort required for a disruptive change. It is interesting to note that |
haha, yes, I think that would work. I really don't want to encourage this however, I think that could be highly confusing 😄 |
Okay, setting milestone 0.16 to add a warning about css or javascript that is automatically included in the HTML. We can then have a think about copying assets in general. |
I'm using an instance of mkdocs as a personal wiki. I like the search and categorization capabilities but, first of all, I like mkdocs autopopulating from any md file I throw into docs without further effort. I understand this is not the main use case for mkdocs, but I would be sad to lose that feature. It's ok for other assets not to autopopulate, though. |
I would argue this is one of the main use cases for MkDocs. Allowing people to easily write good documentation and then easily present that to users is probably one of the top goals for the project. However, I don't think anyone is suggesting removing the automatic inclusion of Markdown files, if you don't define which to include in the config. This issue is about all the related files, like images or css or html |
(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.The text was updated successfully, but these errors were encountered: