I have written some custom CSS I would like to be included in a Mkdocs site hosted by ReadTheDocs. It is not working because RTD isn't serving the CSS file.
I have a .readthedocs.yml file that asks RTD to use Mkdocs:
version: 2
mkdocs:
configuration: .mkdocs.yml
My .mkdocs.yml file references the fact that I'm using a custom CSS file:
docs_dir: my-docs-directory
theme:
name: 'material'
extra_css:
- '.mkdocs.material.css'
ReadTheDocs reports that the docs built fine, but when I load them the custom CSS isn't in effect. If I open the browser Console I see this error:
Refused to apply style from 'https://private-site.readthedocs-hosted.com/en/latest/.mkdocs.material.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.
If I open the CSS file URL in its own tab I see a "404 - Not found" page.
I tried including the CSS file in both root (where .readthedocs.yml and .mkdocs.yml live) and in my docs directory (my-docs-directory), but neither work.
I think I need RTD to somehow know to serve the CSS file up as a static file, but all guidelines I could find about this are specific to Sphinx.
Please help! Thanks!
I believe this issue is due to the dot at the beginning of .mkdocs.material.css. It looks like MkDocs (mkdocs build, I used MkDocs v1.0) won't copy hidden files -- the dot at the beginning denotes a hidden file on Unix systems -- to the output directory. I think if you rename the file to be mkdocs.material.css without the leading dot and update the reference in your mkdocs.yml, it should work.
The more cryptic error message you see on Read the Docs (Refused to apply style ...) is because the link tag (<link>) to the CSS file is still generated in the build output but MkDocs didn't actually copy the CSS file because it was hidden. As a result it gives a 404. Read the Docs sends a header telling browsers to do strict MIME checking which is an important security measure when handling user uploaded files. Because there's a link to a CSS file but the response is a 404 with HTML, the browser rejects the style.
Related
I'm still relatively new to making webs, I read about adding version numbers to CSS files so the browser loads the newest version, I changed my style.css name to style.css?v=1 on my HTML, do I need to change the file name of the CSS too? Forgive me if my lingo is weird
As #Dan Canetti suggested - this is the comment that I had above - included as an answer so the OP can resolve the question.
No - you do not need to change the file name of the .css file. The query string that is appended to the file name in the browser is used to allow the sourcing of the file without changing it.
If you have a styles.css and you call it with styles.css?v=1 - then it will still load. The difference is that the browser can cache the content and if it already has loaded styles.css?v=1 then it will load it from the cache - not the server.
Then if you make some change and you then call styles.css?v=2... the v2 version will not be in the loal cache and so the browser will retieve it from the server
EDIT: Waylan's answer did the trick! Thanks!
I'm trying to zip .html files of docs to send to a customer. The goal is to have the same experience as navigating an actual website.
When opening the .html files, any link that is clicked goes to the parent folder, rather than the specific .html. For example, if I click on the link for the configuration page, it takes me to this parent folder (shown in the picture) with an index.html to the actual page. This is only happening in my local instance when I'm going through the .html files -- not when I'm navigating the built .md (using MkDocs).
macOS Catalina, 10.15.3
MkDocs
Markdown
You probably want to set use_directory_urls: false in your mkdocs.yml config file.
The behavior you are seeing is based on a feature of web servers. If you request a directory (for example /foo/) then the server will return the index page within that directory (/foo/index.html). MkDocs makes use of this feature to provide "pretty URLs" (URLs which do not have file extensions).
Therefore, when building the site, MkDocs will convert every page to an index file within a directory and will also rewrite all of the internal links to point to those locations. So long as the pages are hosted on a server which is configured to serve index pages (most are by default), this is not an issue.
However, if you are browsing the files locally without a web server or happen to be using a server which is not configured to handle index files, then you will see the behavior you are getting. You have two options:
Use a properly configured server.
Turn off the feature with MkDoc' use_directory_urls configuration setting.
To do the latter, add the following to your mkdocs.yml config file:
use_directory_urls: false
Then rebuild the site with mkdocs build. Now your pages will not all be index files.
Note that while this allows you to browse the files without a server (using file:///), due to browser security policies, search will no longer work within a MkDocs site. Therefore, it is recommended that you always use a server. That also explains why the default configuration expects a server.
I have created a website using css, js and jquery, and everything works fine on my local machine, but after uploading it to the server, it was only reading the index.html file, leaving out the css and js. Below you can see the website's structure, after being uploaded to the server, on FileZilla.
enter image description here
I have decided to delete everything, re-check the paths and upload them again, but now all I get is a "403 Forbidden" message, saying that "You don't have permission to access / on this server."
Check file permissions of all the files.
Triple check file paths
/www/style.css
./www/style.css
^ Notice this dot
The above are two completely differnet paths. My guess is, that the second one is the correct one and should lead to style in your specific example
Up until a few weeks ago, any HTML files I linked to an iFrame would be shown within the frame. All of a sudden, Chrome and Firefox will now ask me whether I want to download the HTML file in the iFrame. It's an Apache server and I do believe it was upgraded recently. How it was upgraded, I am not sure. I was wondering if it had anything to do with the way certain MIME types get processed within an iFrame.
Note: Chrome and Firefox are the only browsers that I've tested this with. I don't think this is a browser issue though.
It's very likely the mime-type configuration is no longer properly set up on your Apache server. Most of the time, the server configuration sets the mime type of the returned object based on the file extension you're requesting. If your file extensions have changed, or if you're using dynamic URLs that don't end in ".docx"), e.g. that get processed by an intervening app server to return the file without themselves setting the MIME type, then the browser has no way of knowing what the contents are, and correctly concludes that the best thing to do is to just gives you the contents in a file.
So... set the extension of the file you're downloading to .docx or .doc. If you're using a default Apache config, that might do it. If that doesn't work, change the mime type of the returned object based on a URL filter configuration in your apache.conf or other apache config file. Or if using dynamic URLs, explicitly set the mime type in your code to one of the following:
.doc - application/msword
.dot - application/msword
.docx - application/vnd.openxmlformats-officedocument.wordprocessingml.document
.dotx - application/vnd.openxmlformats-officedocument.wordprocessingml.template
.docm - application/vnd.ms-word.document.macroEnabled.12
.dotm - application/vnd.ms-word.template.macroEnabled.12
I have a basic web application packaged as an EAR deployed on GlassFish.
The web module has some html files.
The html files have a common footer, an html file, that I would like to extract out and make an include.
When I do, and put:
<!--#include virtual="insertthisfile.html" -->
in an html file, it does not work.
Should this work?
This is a technique called Server-Side Includes (SSI). It may not be enabled on your web host. If it is, sometimes they force a .shtml extension to be required for included files, so try renaming your file insertthisfile.shtml.
If that doesn't work, you might be able to enable SSIs in a .htaccess file (assuming your web server is Apache). You can find instructions on how to do this by googling. There's a decent set here.
If that fails, I would contact your web host and see if they have SSIs enabled.
Should this work?
Perhaps, at some special settings, with some experienced programmer, this could be useful.
In my case the include statement seems to be ignored.
I could include some text with
(embed src="include.shtml")
(/embed)
Above, I type () instead of angular brackets.
With the "embed", the setting in the header of the page does not apply to the included text; it should be repeated again, and, by default, the result is ugly.
It looks strange, as if the designers of the html did not build-in the very basic tool, the include command. For short articles, the include could save an order of magnitude in the size of files.