I am preparing documentation using MkDocs and trying to generate the documentation using readthedocs. I followed the user guide but readthedocs does not seem to communicate with my uploaded .md files in my GitHub project. Instead of reading my docs/index.md file, the document generated by readthedocs says
This is an autogenerated index file.
Please create an index.rst or README.rst file with your own content under the root (or /docs) directory in your repository.
If you want to use another markup, choose a different builder in your settings. Check out our Getting Started Guide to become more familiar with Read the Docs.
© Copyright 2022. Revision 8d3f60c9.
Built with Sphinx using a theme provided by Read the Docs.
One possible issue is that the builder is Sphink instead of MkDocs, so I changed the document type to "MkDocs" in admin-> advanced setting->documentation type in readthedocs but this does not solve the issue.
I then followed the instruction in readthedocs about getting started with mkdocs, import documentation, and configuration files for Mkdocs to set up configuration files as well as requirements but none of them work.
It would be much appreciated if anyone could help me resolve this issue.
I further navigated to https://shaarp-single-interface.readthedocs.io/en/latest/README.html.
The structure in the link above does contain all the nav panels I want but this page no longer maintains the readthedocs theme.
SHAARP_Single-Interface
Search docs
Home
Installation and Setup
Simulation and Analytical Methods
Input Parameters
Output Results
Examples
SHAARP_Single-Interface
Docs »
404
Page not found
Built with MkDocs using a theme provided by Read the Docs.
However, if accessing the docs using "view docs" in readthedocs, it directs me to https://shaarp-single-interface.readthedocs.io/en/latest/, which does not contain any panel I have prepared.
It seems that the building process was fine but the docs will need some time (maybe 1-2 hours) to update.
A similar issue was reported. Autogenerated index file in readthedocs
Related
TLDR: GitHub Pages isn't working.
I have a little knowledge on GitHub and tried multiple fixes to no avail. One repository is only showing readme file contents.
Please explain in lamest terms.
New to web development, I finally was able to complete my first site, but I'm unable to actually deploy the files for some reason; please forgive me, I literally have no idea what any of the git terminologies are.
I purchased a pro subscription in order to keep the repository private and the site public.
Every file is present in what seems to be the main root directory, but nothing is being actually presented.
I've created two different repositories in an effort to fix this, as I've seen different methods are available.
The first repository includes a README file because I was originally instructed to do so, however, all the site link does is present that README file's contents;
I also attempted to add a permalink fix within the file, but all it did was add that text to the other text presented.
The second repository in question literally greets me with nothing but a 404 error.
The solution I tried for the second repository was to have the repository name share my username as well since that seems to be where the site's link originates, but no present changes have occurred.
Finally, the waiting game solution hasn't beared any fruit yet either aside from updating the README file's contents.
All help is very much appreciated.
Check first:
Your GitHub repository name, which depends on the type of GitHub Pages you are creating
If you're creating a user or organization site, your repository must be named <user>.github.io or <organization>.github.io.
your GitHub Pages Publishing source
If you use the default publishing source for your GitHub Pages site, your site will publish automatically. You can also choose to publish your site from a different branch or folder.
You can add more pages to your site by creating more new files.
Each file will be available on your site in the same directory structure as your publishing source.
For example, if the publishing source for your project site is the gh-pages branch, and you create a new file called /about/contact-us.md on the gh-pages branch, the file will be available at https://<user>.github.io/<repository>/about/contact-us.html.
Make sure you have GitHub Pages enabled for every repository and that it's set to the branch you want to publish by checking your Pages settings at github.com/<user>/<repo>/settings/pages. If enabled, there should be a link on that page that takes you to the site.
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'm having an issue where ReadTheDocs doesn't appear to be updating with new documentation files. Specifically, we added these files (everything d3 related here) but in ReadTheDocs they don't appear (see [this][4]); What I'd expect to see is this:
Here's a screenshot of the correctly built docs
Note the "Empirical D3 Wrapper" link, which is in the docs when built locally using "make html" but not evident when built on ReadTheDocs.
There aren't any errors in the build log that I can find, and I've tested building locally with an identical version of Sphinx to what ReadTheDocs uses.
I'm at a loss as to what could be causing this--Suggestions?
I've added my cms as an external library in PhpStorm:
I just wanted to know if there is an option to upload (deploy) these files too? I always have to switch to my cms and open it itself as a project to be able to upload its files.
I've found nothing in the documentation also.
If it's not part of the project root/outside of the project -- then no.
But you can make it part of the project by:
adding it as Additional Content Root (Settings/Preferences | Directories) -- it will be listed as additional node in the Project View panel (similar to actual project's main folder)
or just symlink it (e.g. a subfolder inside the project root that is symlink to outside folder).
Please note that in both cases such folder becomes part of the project so the search routine will take those files into consideration as well as other functionalities (find usages; look for errors in a code; TODO's etc.). You may also accidentally edit your CMS core files and IDE will not tell you anything (in case of External Library it will notify you about this).
I have created a static website using Jekyll and recently upgraded from Jekyll 2.5.3 to 3.1.1. Since Jekyll version 3 .html extensions are dropped from internal links, which gives us nice urls. This I love.
Since all pages are still created using the html extension, verifying the site using HTML Proofer now fails, because it detects dead links.
This breaks my continuous integration system (setup according to jekyllrb ci docs) on Travis CI.
So, I love the .html-less links AND that html-proofer checks my internal links. But how do can I verify the .html-less links using html-proofer?
There is a Jekyll talk on this subject; as well as a Github PR. Neither helps me very much.
I've got a new working PR for this in https://github.com/gjtorikian/html-proofer/pull/311. You can use it like this until it gets merged:
Gemfile: gem 'html-proofer', github: "Floppy/html-proofer", branch: "jekyll-3-extensionless-links"
It adds a assume_extension option: HTML::Proofer.new("./_site", assume_extension: ".html").run
Or you can use the --assume-extension=.html command line switch if you're using the binary.
Edit: this was released and available in html-proofer 3.0.4 I'm currently using. The api is slightly different, assume_extension has become a switch, defaulting to false. So you'd do:
HTML::Proofer.new("./_site", assume_extension: true).run
or
htmlproofer ./Site --assume-extension
It works in combination with the extension options if you'd like a different extension for your pages than the default .html.