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.
Related
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
I use sphinx to build html documentation, and am in the middle of open-sourcing some of my company's private repos.
Internally, we serve documentation from an S3 bucket through Cloudfront so we can put access controls in front of it. But for open source, I figured publishing via Github Pages would be the path of least resistance.
However, I cannot get the service to work correctly.
Here is my repo, with my index.html in the /docs folder.
Here is the site, which is not applying any of the linked css, and with all page links broken.
I tried to isolate the issue by making a test repo with just the built documentation, and publishing from master.
As you can see, this one does not even try to serve the index.html, I just get a 404 page.
These files work both locally and when serving from AWS, so I'm a little at a loss for why Github Pages is not serving it correctly. I feel like I must be making some sort of dumb oversight. If anyone with more experience could take a look and point me toward the error of my ways I would really appreciate it. I'm a backend engineer for the most part so website logic is a little outside my normal wheelhouse. Thanks in advance!
To anyone else running into the same thing, I figured it out. Because I am pre-building the site in my CI/CD pipeline, I don't need jekyll to build the site for me, and need to add an empty config file for it.
From [here][https://www.docslikecode.com/articles/github-pages-python-sphinx/]:
Next, you set up the .nojekyll file to indicate you aren’t using
Jekyll as your static site generator in this repository.
Thank you for your help!
You need a _config.yml, and you need to enable github pages on Master for the repo (go to settings). After that, you also need a Gemfile it the following:
source 'https://rubygems.org'
gem 'github-pages'
Normally, the GitHub pages site needs to be in the root, and yours looks like it's in a /docs folder, so I'm sure you can Google how to do that. It might not be possible though with GH pages, I'm not sure.
If it must be a subfolder and not the root of the project maybe something like this would work: https://gist.github.com/cobyism/4730490
Heres whats in my _config: for barebones sites:
permalink: pretty
sass:
sass_dir: _scss
style: compressed
I'm sure you can leave sass out
I'm developing a Wordpress "widget" that is going to be a little react app. I've chosen create-react-app for this purpose.
Now I can see how to run the development server standalone easily enough, but I'd like to develop it while it sits inside the Wordpress website. I've created a trivial "Custom HTML" widget:
<div id="root"></div>
<script type="text/javascript" src="http://localhost:8080/static/js/bundle.js"></script>
This does not seem to work however...
Note I came up with /static/js/bundle.js by looking at the requests in the network tab when loading http://localhost:8080 directly, which is the prescribed way to access the dev version of the app.
So how do I access the development version of the app (with all the live reloading goodness) while embedded on my local version of the Wordpress site?
I had this same problem today in a PHP app I am developing. It is very frustrating to embed a create-react-app in development mode, and I had to consult a lot of different resources to learn how to do so. Here is a summary of my findings.
Using an iframe
Using an iframe to embed the create-react-app, as #quickshiftin suggests, is not a bad idea, but if you wish to pass configuration to the embedded SPA by calling methods or setting global variables in Javascript, it will not work* -- as the MDN documentation says (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#scripting), iframes are subject to the same-origin policy.
* (Note: I found out after writing most of this answer that there is indeed a way to bypass the same-origin policy. It's called Window.postMessage(), and it's also mentioned in the section of the MDN documentation that I linked above. You may want to consider using that. But if you would like to avoid using an iframe for whatever reason, read on :)
Create-React-App file structure; embedding in production mode
The first thing you must know is that embedding bundle.js is not enough -- create-react-app builds multiple JS files that need to be embedded using <script> tags in the correct order. This blog post by Jeremiah Tabb describes the file structure of the bundled code and suggests a way to embed the create-react-app in production: https://betterprogramming.pub/how-to-embed-a-react-application-on-any-website-1bee1d15617f
The filenames of the bundled code contain hashes which change at every build. The hashing can't be disabled, it's a WONTFIX in create-react-app (https://github.com/facebook/create-react-app/issues/821). So, to get the bundled js filenames for a production build, in PHP, you can just traverse the build/static/js directory and output one <script> tag per .js file you find. (It may be wasteful to always request all chunks, but I haven't yet taken the time to look into the right way to do it.)
Development mode looks for chunks under the wrong path
But in development mode, which is your actual question, it is handled a bit differently. The index.html served by the dev server only loads three scripts initially: bundle.js, vendors~main.chunk.js and main.chunk.js. The other chunks are loaded dynamically. You can try embedding those three scripts on your Wordpress page, but you will find that at runtime, the 'bootstrap' code generated by Webpack looks for the chunks at the wrong URL, using e.g. localhost instead of localhost:3000, resulting in a chunk loading error.
PUBLIC_URL and "homepage" don't work in development mode
According to the Create-React-App documentation and various other answers on this site, you're supposed to be able to use the environment variable PUBLIC_URL or the key "homepage" in package.json to override the hostname and port where the JS code is served so that the chunks will load, but these settings don't do anything in development mode. This is an open issue in create-react-app: https://github.com/facebook/create-react-app/issues/9001
Workaround using npx patch-package
You might think you are in trouble and will have to eject your project and modify the webpack configuration yourself to get this working. But fortunately, there is a workaround described here in a comment by SergeyVolynkin which solves the problem without ejecting, using npx patch-package to patch react-dev-utils:
https://github.com/facebook/create-react-app/issues/9001#issuecomment-838370686
What SergeyVolynkin does not mention is that, after creating the patch and checking it into VCS, you should set up patch-package in your package.json so that the patches will be applied by npm / yarn when you run yarn / npm install. See the documentation for patch-package here: https://github.com/ds300/patch-package#set-up
Summary
After applying SergeyVolynkin's patch, I was able to get the development build embedded in my PHP app. I used the following scripts in my package.json:
"scripts": {
"start": "PORT=1234 PUBLIC_URL=http://localhost:1234 WDS_SOCKET_PORT=1234 react-scripts start",
"postinstall": "patch-package"
}
And I used the following lines in the HTML served by my PHP app:
<script src="http://localhost:1234/static/js/bundle.js"></script>
<script src="http://localhost:1234/static/js/vendors~main.chunk.js"></script>
<script src="http://localhost:1234/static/js/main.chunk.js"></script>
By doing this, I could embed an app created using create-react-app in dev mode in my PHP app.
I'm contributing to an open source project that has its documentation built in Jekyll and hosted on Github Pages. I'm trying to add a redirect in the documentation, so I've forked it and am using jekyll-redirect-from in the fork. However, the redirect simply doesn't seem to be applied. That is, the jekyll build folder doesn't contain any static file to hold the <meta redirect> html that jekyll-redirect-from is supposed to generate. Instead, when I visite the URI that's supposed to be redirected, I just get a 404.
I've followed all the steps in the jekyll-redirect-from docs, including:
Adding jekyll-redirect-from to the Gemfile (code)
Adding it to my _config.yml file (code)
Adding the redirect_from key to my page's front matter (code)
I'm using jekyll 2.5.0 and jekyll-redirect-from 0.8.0 (the full gemfile is linked above). I'm building the project with bundler (using bundle exec jekyll serve), which is how the project's always been built.
Jekyll isn't showing any errors—the static file that should hold the redirect simply doesn't show up.
I can't for the life of me figure out the problem. Maybe I'm overlooking something obvious, or maybe there's some sort of subtle incompatibility in my dependencies?
D'oh. The issue was that the safe option needed to be set to false for the plugin to run. This tripped me up because I know Github Pages sets safe to false as well, and yet jekyll-redirect-from generally runs there. But that appears to be because GH Pages has made an explicit exception to allow it.
My issue was that I had:
redirect_from: /a/path/
redirect_from: /other/path
And repeated directives don't work like that in YAML.
Instead, it should be:
redirect_from:
- /a/path/
- /other/path
On http://github.com developer keep the HTML, CSS, JavaScript and images files of the project. How can I see the HTML output in browser?
For example this: https://github.com/necolas/css3-social-signin-buttons/blob/master/index.html
When I open this it doesn't show the rendered HTML of the code of author. It shows the page as a source code.
Is it possible to see it as rendered HTML directly? Otherwise I always need to download the whole ZIP just to see the result.
The most comfortable way to preview HTML files on GitHub is to go to https://htmlpreview.github.io/ or just prepend it to the original URL, i.e.: https://htmlpreview.github.io/?https://github.com/bartaz/impress.js/blob/master/index.html
If you don't want to download an archive you can use GitHub Pages to render this.
Fork the repository to your account.
Clone it locally on your machine
Create a gh-pages branch (if one already exists, remove it and create a new one based off master).
Push the branch back to GitHub.
View the pages at http://username.github.io/repo`
In code:
git clone git#github.com:username/repo.git
cd repo
git branch gh-pages
# Might need to do this first: git branch -D gh-pages
git push -u origin gh-pages # Push the new branch back to github
Go to http://username.github.io/repo
🚩 Message from RawGit's creator and owner on https://rawgit.com:
RawGit has reached the end of its useful life
October 8, 2018
RawGit is now in a sunset phase and will soon shut down. It's been a fun five years, but all things must end.
GitHub repositories that served content through RawGit within the last month will continue to be served until at least October of 2019. URLs for other repositories are no longer being served.
If you're currently using RawGit, please stop using it as soon as you can.
When I tried to use it, I got:
403 Forbidden
RawGit will soon shut down and is no longer serving new repos. >> Please visit https://rawgit.com for more details.
You can use RawGit:
https://rawgit.com/necolas/css3-social-signin-buttons/master/index.html
It works better (at the time of this writing) than http://htmlpreview.github.com/, serving files with proper Content-Type headers.
Additionally, it also provides CDN URL for use in production.
It's really easy to do with github pages, it's just a bit weird the first time you do it. Sorta like the first time you had to juggle 3 kittens while learning to knit. (OK, it's not all that bad)
You need a gh-pages branch:
Basically github.com looks for a gh-pages branch of the repository. It will serve all HTML pages it finds in here as normal HTML directly to the browser.
How do I get this gh-pages branch?
Easy. Just create a branch of your github repo called gh-pages.
Specify --orphan when you create this branch, as you don't actually want to merge this branch back into your github branch, you just want a branch that contains your HTML resources.
$ git checkout --orphan gh-pages
What about all the other gunk in my repo, how does that fit in to it?
Nah, you can just go ahead and delete it. And it's safe to do now, because you've been paying attention and created an orphan branch which can't be merged back into your main branch and remove all your code.
I've created the branch, now what?
You need to push this branch up to github.com, so that their automation can kick in and start hosting these pages for you.
git push -u origin gh-pages
But.. My HTML is still not being served!
It takes a few minutes for github to index these branches and fire up the required infrastructure to serve up the content. Up to 10 minutes according to github.
The steps layed out by github.com
https://help.github.com/articles/creating-project-pages-manually
I read all the comments and thought that GitHub made it too difficult for normal user to create GitHub pages until I visited GitHub theme Page where its clearly mentioned that there is a section of "GitHub Pages" under settings Page of the concerned repo where you can choose the option "use the master branch for GitHub Pages." and voilà!!...checkout that particular repo on https://username.github.io/reponame
Also, if you use Tampermonkey, you can add a script that will add preview with http://htmlpreview.github.com/ button into actions menu beside 'raw', 'blame' and 'history' buttons.
Script like this one:
https://gist.github.com/vanyakosmos/83ba165b288af32cf85e2cac8f02ce6d
I have found another way:
Click on the "Raw" button if you haven't already
Ctrl+A, Ctrl+C
Open "Developer Tools" with F12
In the "Inspector" right-click on the tag and choose "Edit HTML"
Ctrl+A, Ctrl+V
Ctr+Return
Tested on Firefox but it should work in other browsers too
If you have configured GitHub Pages you can get your public url like as:
https://<username>.github.io/<repository>/index.html
where <username> & <repository> will be the placeholder for username & repo name respectively
So, the result will be like this:
http://necolas.github.io/css3-social-signin-buttons/index.html
If it is an organization with GithubPages enabled in all the repositories it will be something like:
https://<org>.github.io/<repository>/
Two approaches (for public repositories) worked well for me: both VERY SIMPLE and ABLE TO RENDER COMPLEX HTML PAGES with links to local CSS files and local JAVASCRIPT/VUE files.
METHOD 1 - With GitHub pages
To set up, go to: https://github.com/YOUR_ACCT_NAME/YOUR_REPO_NAME/settings/pages (see screen shot below)
Example of my original HTML page on the repo: https://github.com/BrainAnnex/life123/blob/main/experiments/life_1D/diffusion/diffusion_1.htm
How it looks rendered: https://brainannex.github.io/life123/experiments/life_1D/diffusion/diffusion_1.htm Notice how all the styling, graphics and interactive controls are all good :)
METHOD 2 - With free service raw.githack.com
Go to https://raw.githack.com/ and enter the full URL of yourpage (including the "/blob" part); e.g. https://github.com/BrainAnnex/life123/blob/main/experiments/life_1D/diffusion/diffusion_1.htm
Then the site generates 2 links that work quite well :)
A good alternative if GitHub pages were to become unavailable!
This isn't a direct answer, but I think it is a pretty sweet alternative.
http://www.s3auth.com/
It allows you to host your pages behind basic auth. Great for things like api docs in your private github repo. just ad a s3 put as part of your api build.
If you are using an enterprise Github, you might not want to have a public facing github pages. One thing that worked for us is to:
For a HTML file in: https://github.private-repo.com/team/project/blob/master/order.html
Following is the URL that opens in a browser and retrieves the latest file as HTML:
https://github.private-repo.com/pages/team/project/order.html