Is it possible to create documentation of certain projects within the mkdocs framework?
I am aware of server deployment via mkdocs serve. We can also once the documentation reached a certain level we like perform mkdocs build and this will create a site folder, which we can in fact download locally and browse by opening the index.html file.
This approach however is not perfect, as every time we can switch a tab, it runs into a between step where we have to manually matches with another HTML page we are interested in.
Is it possible to save how save the entire mkdocs locally or as a pdf?
It must be for local usage but without a server approach.
According to documentation, you can set this values in mkdocs.yml configuration file:
site_url: ""
use_directory_urls: False
site_url must be set to an empty string if you want to use file:// scheme.
use_directory_urls should be set to false for links between pages to work correctly.
You also need to disable the search plugin or use another plugin, which supports file:// scheme.
Note: not every theme can display properly in offline mode.
Related
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.
So when I type npm run generate Nuxt generates my project into the dist folder. In that folder I can find a folder called _nuxt where I have .js files and the index.html file but when I open it in a browser it doesn't show anything.
So, my question is: Aren't those static files?
When you work with the CDN served vue.js you have the html file and you click and everything is showed on the browser because those .html files are static, they don't need an internal localhost server. Why npm run generate doesn't do the same? Or how can I see those generated files?
As #aljazerzen explained, Vue,js doesn't do SSR out of the box, one of the aims of Nuxt.js is to provide SSR for you, as a benefit you can also generate a static version of your website. If I get what you want correctly, what you want to do is that when you open your index.html (the one that Nuxt.js generates for you) you can see your functional webpage. When you're accessing your website as a file:/// url, your browser (at least I've seen it happen with Chrome) doesn't load your .js files.
I don't have any Nuxt generated websites at hand so I can't tell you exactly why this happen. But this is my guess: when Nuxt generate those files it gives them a src that can't be accessed as file:///, maybe something as /your_js.js, that when it tries to load it, thinks it's the / of the root folder instead of relative to your website's root (/).
The solution to this problem is to serve your assets using any web server. According to Nuxt.js's documentation:
nuxt generate :Build the application and generate every route as a HTML file (used for static hosting).
You could do a quick test and use a simple web server by typing:
python -m http.server
In the folder that contains your generated assets.
Hope this helps!
Nuxt uses server side rendering.
You can read more here.
To generate static HTML files, run:
nuxt generate
Explanation: Vanilla Vue.js application is rendered only when the page loads and JavaScript can start running. This means that some clients that do not have JavaScript enabled (web crawlers) won't see the page. Also for a brief second before Vue.js can render the page, there is blank screen, when plain HTML files could already be visible.
Now, server-side rendering (SSR) is a technique for rendering a single page app (SPA) on the server and then sending a fully rendered page to the client. The client’s JavaScript bundle can then take over and the SPA can operate as normal.
This can also help with SEO and with providing meta data to social media channels.
But on the downside (as you mentioned), such application cannot be hosted at a CDN, since you have to have a Node.js process running to render the page.
In my opinion, SSR is redundant with SPAs if what you are building is actually an application and not a website. A website should mostly display information and should not be interactive. It should leverage web-based mechanisms such as links, cookies and plain HTML with CSS. In the contrast, web application (eg. Vue.js application) should be more like a mobile application: it is larger to download, but performs better and offers much more interactive experience. Such application does not need server-side rendering, since we can wait for it to load a bit more and because it shouldn't be indexed by search engines (it is not a website).
When a website doesn't have an index.html file, the navigator displays an auto generated page right ?
Here is an example of what I mean.
This page is very handful to explore a website, but sadly it is only displayed when there is no index.html page.
Is it possible to access such a page on a website, even though index.html exists in the folder ?
I'm using Opera, but I have tried other navigators and none of the common ones seems to do what I want ^^
Thanks for reading
This is not an auto generated page. It is directory browsing of server which can be enabled/disabled through server control panel (or using .htaccess in linux servers).
When you have default document (like index.html) in a folder, the server servs the default document instead of directory browsing. So if you want to let directory browsing when you have index.html, you have to clear the index.hmtl from the list of default documents. This can be done using IIS settings (if you have access to server) or through hosting control panel in website settings (in shared hostings) (or by direct editing of web.config or .htaccess)
the navigator displays an auto generated page
No. This has nothing to do with the browser. The browser displays whatever the server returns. Nothing more, nothing less.
What you're seeing on that link is from the Apache web server. That web server is configured to (and can be configured not to) return a generated directory listing when no default response can be determined.
The "default response" might be index.html, or default.html, or literally anything that the web server is configured to look for by default. (Those are just, well, the common defaults.)
In many modern web applications the concept of a "page" doesn't even really mean the same thing, because things like MVC frameworks don't just browse directories for .html files but instead examine requested routes and generate responses from code.
Is it possible to access such a page on a website, eventho index.html exist in the folder ?
No. Because that "page" doesn't exist. The web server returned that to you because it was configured to. If it's not configured to then that data doesn't exist.
We started having our project's docs on readthedocs site (say http://abc.readthedocs.org). For various reasons we now moved to our own web servers with new domain (http://abc.io).
We want to bring down http://abc.readthedocs.org gracefully so that our project documentation is not broken all across the internet.
One way we are thinking is to have "redirects" from all pages with prefix (http://abc.readthedocs.org) to (http://abc.io).
But, I don't see any redirection options in readthedocs site that provides redirection to completely new domain. Readthedocs only allow redirection within different pages under same domain.
Any pointers on how I can proceed would be very helpful.
Read the Docs offers several kinds of user-defined redirects:
Prefix redirects (e.g. /dev/... -> /en/latest/...)
Page redirects (e.g. [/$lang/$version]/example.html -> [/$lang/$version]/examples/intro.html)
Exact redirects (e.g. /dev/install.html -> /en/latest/installing-your-site.html)
To migrate from an old Read the Docs project to somewhere else, the project is more involved:
Add an Exact Redirect from /$rest to https://new.domain/
Deactivate all versions of the old project, except latest (which can't be deactivated)
Create a repository with a Sphinx project that only contains an index.rst with the following markup:
.. meta::
:http-equiv=Refresh: 0; url='https://new.domain/en/latest/'
Change the repository URL on https://readthedocs.org/dashboard/oldproject/edit/ to such repository
I added the following section to my index.rst:
.. raw:: html
<script type="text/javascript">
if (String(window.location).indexOf("readthedocs") !== -1) {
window.alert('The documentation has moved. I will redirect you to the new location.');
window.location.replace('http://cosmo-docs.phys.ethz.ch/cosmoHammer');
}
</script>
On the ReadTheDocs Admin page, the "Exact Redirect" form of redirection allows other domains in the "to URL" field. But it only seems to redirect one page per rule. That is, it requires an "Exact" match. I was hoping for some mod_rewrite magic using (.*) and $1. But that is not set up.
Another idea that works (but is clunky) is to create a temporary repository with a docs folder that uses markdown. The index.md file can consist of a refresh:
<meta http-equiv="refresh" content="0; URL=https://new.location">`
You can also add html with a direct link in case the refresh doesn't work.
The conf.py file can be:
from recommonmark.parser import CommonMarkParser
source_parsers = {'.md': CommonMarkParser}
source_suffix = ['.md']
master_doc = 'index'
Commit this repository to github (or other host) and change the project URL for your RTD project to this temporary repository. You can create tags for the temporary repos. to match those of your actual repository. Then make sure ReadTheDocs builds each version. If all goes well, the home pages of each version will redirect to wherever your refresh sends them.
It would be nice if the Redirects available on the Project Admin page would allow redirects of prefixes to other domains.
Lets say I have a directory of .html files, accessible by the app server, and I want to display to users so they can access them with their browser:
/import/tps-reports/index.html
/import/tps-reports/report1.html
/import/tps-reports/report2.html
Is there a way I can expose the tps-reports directory to do this so that a user can access them via:
http://www.example.com/tps-reports/index.html
http://www.example.com/tps-reports/report1.html
Also, keep in mind that index.html may reference the other pages:
Report 1
So those links need to work as well.
Here is a possible answer:
http://docs.oracle.com/cd/E19776-01/820-4496/geqpl/index.html
You can set up an alternate doc root so that certain URI patterns point to different paths.
The examples are only really showing relative paths though...I wonder if its "ok" to use this to reference local file systems.