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.
Related
I currently have a simple website, hosted on github pages with a file structured in hierarchical directories as shown below:
/foobar.com
/css
/js
/images
/html
/news
/news_content
fizz.html
buzz.html
news.html
about.html
contact.html
index.html
However, when I am on the buzz webpage for example, this has resulted in the URL to become:
https://foobar.com/html/news/news_content/buzz.html
Is there a way to change this URL so that it doesn't show all the folder directories and instead, just the file itself i.e. https://foobar.com/buzz.html as I don't want to separate all the individual HTML files into separate folders?
Yes, you can change the URL to be more user-friendly by using server-side URL rewriting or client-side JavaScript.
For server-side URL rewriting, you'll need to use a web server such as Apache or Nginx and configure it to rewrite the URLs. You can find more information on how to do this for Apache or Nginx by searching for "URL rewriting" on their websites or forums.
For client-side URL rewriting, you can use JavaScript to manipulate the URL shown in the browser's address bar. However, this method may not be ideal for search engines or users who have JavaScript disabled.
If you are using GitHub Pages to host your website, you might be able to achieve URL rewriting by using Jekyll. Jekyll is a static site generator that supports URL rewriting and can be used in combination with GitHub Pages to host your website. You can find more information on how to do this by searching for "Jekyll URL rewriting."
How a URL is resolved to a resource depends on the HTTP server and/or the server side programming language you are using.
Github Pages provides no features that allow anything other than a direct reflection of the directory layout in the URL.
The closest you could come would be to write a program that transformed the input (the file structure you want to work with) into the file structure that Github Pages will express as the URLs you desire (and then run it as a build step that takes the pages out of your working branch and into your gh-pages branch; possibly you could use actions to do this).
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.
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 I have a Site created with Typo3. I also have a domain which is linked to the folder of the Typo3 Installation. www.example.org
I created a Subdomain and linked it to the same folder and used the Main Domain for something else.
But now everything on the Subdomain still has the URL Structure of the main site so when I open up sub.example.org all the Links and Images still have the URL from www.example.org/...
I exported the Database and replaced every URL with notepad++ and imported it again. But that didnt change anything. What do I do wrong?
There are two (three with realurl) places where you need to look if changing the domain of a TYPO3 site, if everything is done by the book and noone hardcoded the domain all over the place or something.
Usually you do not need to work in the database directly.
After doing the changes, make sure to clear the caches (install tool in 6.2+, "all caches" in earlier versions).
First:
There are two TypoScript settings that influence the generated URL: config.baseURL and config.absRefPrefix.
The recommended way to use those is to not set config.baseURL (would result in a <base> tag in the HTML <head>), and set config.absRefPrefix to the subpath where TYPO3 is, relative to the document root. If TYPO3 lies directly in the document root, set it to /.
Second:
In the database, there are "Domain Records". They are usually located on the root page of a site. Change those to the new domain.
Third (with realurl only):
Check the realurl configuration file, usually located in typo3conf/realurl_conf.php. Depending on your setup, the old domain name is used there and needs to be changed.
I've uploaded several files to my server and it's really quite baffling. The home page is saved as index.html, and when I type in the URL of said page it miraculously, and quite successfully shows the right page. What about my other pages? I have linked to them from the home page with the following code:
About Us
How does my html file, presumably called about.html, supposed to know that its URL is "http://www.example.com/about/"? I am dubbing this "The Unanswered Question" because I have looked at numerous examples of metadata and there is nothing about specifying the URL of a page.
It depends on what type of server you are running.
Static web servers
If it is the simplest kind of static file server with no URL aliasing or rewriting then URLs will map directly to files:
If your "web root" was /home/youruser/www/, then that means:
http://www.example.com -> /home/youruser/www/
And any paths (everything after the domain name) translate directly to paths under that web root:
http://www.example.com/about.html -> /home/youruser/www/about.html
Usually web servers will look automatically for an "index.html" file if no file is specified (i.e. the URL ends in a /):
http://www.example.com/ -> /home/youruser/www/index.html
http://www.example.com/about/ -> /home/youruser/www/about/index.html
In Apache, the filename searched for is configurable with the DirectoryIndex directive:
DirectoryIndex index.html index.txt /cgi-bin/index.pl
That means that every request to a path that ends in a / (and to add yet another rule, under some common settings it will automatically append a / if the path is the name of a directory, for example 'about'):
http://www.example.com/ -> /home/youruser/www/index.html
-> or /home/youruser/www/index.txt
-> or /home/youruser/www/cgi-bin/index.pl
Web servers with path interpretation
There are too many different types of servers which perform this functionality to list them all, but the basic idea is that a request to the server is captured by a program and then the program decides what to output based on the path.
For example, a program might perform different routes for basic matching rules:
*.(gif|jpg|css|js) -> look for and return the file from /home/user/static
blog/* -> send to a "blog" program to generate the resulting page
using a combination of templates and database resources
Examples include:
Python
Java Servlets
Apache mod_rewrites (used by Wordpress, etc.)
Links in HTML pages
Finally, the links in the HTML pages just change the URL of the location bar. The behavior of an HTML link is the same regardless of what exists on the server. And the server, in turn, only responds to HTTP requests and only produces resources (HTML, images, CSS, JavaScript, etc.), which your browser consumes. The server only serves those resources and does not have any special behavioral link with them.
Absolute URLs are those that start with a scheme (such as http: as you have done). The whole content of the location bar will be replaced with this when the user clicks the link.
Domain relative URLs are those that start with a forward slash (/). Everything after the domain name will be replaced with the contents of this link.
Relative URLs are everything else. Everything after the last directory (/) in the URL will be replaced with the contents of this link.
Examples:
My page on "mydomain.com" can link to your site using the Example.com about just as you have done.
If I change my links to about then it will link to mydomain.com instead.
An answer your question
How does my html file, presumably called about.html, supposed to know that its URL is "http://www.example.com/about/"?
First, the file itself has no idea what its URL is. Unless:
the HTML was dynamically generated using a program. Most server-side languages provide a way to get this.
after the page is served, client-side scripts can also detect the current URL
Second, if the URL is /about and the file is actually about.html then you probably have some kind of rewriting going on. Remember that paths, in their simplest, are literal translations and /about is not the same as about.html.
Just use /about.html to link to the page
Theoretically, it's better for URLs in your documents to be relative, so that you don't have to change them in the event you change the domain or the files location.
For example, if you move it from localhost to your hosted server.
In your example, instead of www.example.com/about.html use /about.html.
Given the link above you would need a about page named index.html located in a directory named about for your example to work. That is however not common practice.
I'm a bit confused, but here is some information. Any file named "index" is the default display page for any directory(folder) when trying to view that directory.
All files in a folder are always relative to that directory. So if your link is in a file, within a different directory, then you must type in that directory along with the file. If it is the same directory, then there is no need to type in that directory, just the file name.
about.html doesn't know what it's URL is, its the index.html file that calls your about.html file.
When you're in any given directory, linking to other pages within that directory is done via a simple relative link:
About Us
Moving up a directory, assuming you're in a sub folder (users) perhaps you can use the .. operator to navigate up one directory:
About Us
In your case your about page is in the same directory as the page you're linking from so it just goes to the right page.
Additionally (and I think this may be what you're asking) if you have:
about.html
about.php
about.phtml
about.jpg
for example, and you visit http://www.yoursite.com/about it will automatically bring up the html page and the other pages should be referenced explicitly somewhere if you want them to be used.