I created a "jekyll new xx" site locally. When I run Jekyll serve it works very nicely.
Now, I create a new github repo and a branch gh-pages: https://github.com/pitosalas/deleteme
However when it is rendered as a github page it looks all wrong, like style sheets and other assets are missing.
Update
Steven Perry: Thanks for your response, but I had a typo. I wanted to point to the github repo containing the Jekyll "input" files which are then regenerated into the stuff that is served to the browser. The extra slash in the CSS file is an excellent clue but it is in a file generated by Jekyll I think. I can't edit it directly I need to figure out how to get Jekyll to generate it correctly. Do you know?
<link rel="stylesheet" href="/css/syntax.css">
<!-- ^
/
remove this slash ---
-->
Example
For more info, your problem file is here
default.html
Related
i'm in the process of moving my contributing.md file from the project root to the docs/ directory so it can be with the rest of the documentation. Other markdown files in docs render properly when viewed in github pages. For example, the page
https://jtablesaw.github.io/tablesaw/userguide/toc
renders the page toc.md as expected.
however,
https://jtablesaw.github.io/tablesaw/contributing
returns a 404, while simply adding the .md extension
https://jtablesaw.github.io/tablesaw/contributing.md
returns the page as markdown source
The github project is https://github.com/jtablesaw/tablesaw.
and the contributing.md file is in the docs/ folder.
Zachary's answer is correct but there is a way to modify the jekyll's configuration to include the specific page.
Here is an example: https://masterex.github.io/test-docs/contributing
You have to modify _config.yml as follows:
theme: jekyll-theme-minimal
include: contributing.md
Here is github's relevant help page.
After forking your repo, playing around with it for a bit, and banging my head against the wall because I didn't understand why it wasn't working, I realized something:
Github Pages doesn't support building Jekyll pages from files that have names that Github recognizes for other purposes. These file names include (in addition to their lowercase versions):
CONTRIBUTING.md
ISSUE_TEMPLATE.md
PULL_REQUEST_TEMPLATE.md
ISSUE_AND_PULL_REQUEST_TEMPLATE.md
CODEOWNERS.md
On the other hand, despite that README.md is also a Github keyword file, it looks like Github Pages supports using files with the README.md name because it purposely will interpret them the same way as an index.md or index.html file. See this link from the Github blog for more information.
To answer your specific question on how you could get the file to show at the /tablesaw/contributing path, you could rename it and move it to the /docs/contributing/index.md or /docs/contributing/README.md path.
U̶n̶f̶o̶r̶t̶u̶n̶a̶t̶e̶l̶y̶,̶ ̶a̶t̶ ̶l̶e̶a̶s̶t̶ ̶i̶n̶ ̶t̶h̶e̶ ̶p̶r̶e̶s̶e̶n̶t̶,̶ ̶t̶h̶e̶r̶e̶'̶s̶ ̶c̶u̶r̶r̶e̶n̶t̶l̶y̶ ̶n̶o̶ ̶w̶a̶y̶ ̶t̶o̶ ̶k̶e̶e̶p̶ ̶i̶t̶ ̶w̶i̶t̶h̶ ̶t̶h̶e̶ ̶s̶a̶m̶e̶ ̶f̶i̶l̶e̶ ̶n̶a̶m̶e̶ ̶a̶n̶d̶ ̶h̶a̶v̶e̶ ̶G̶i̶t̶h̶u̶b̶ ̶P̶a̶g̶e̶s̶ ̶b̶u̶i̶l̶d̶ ̶a̶ ̶p̶a̶g̶e̶ ̶f̶o̶r̶ ̶i̶t̶.̶
Edit: #Master_ex notes correctly that you can use the include configuration option in the _config.yml file to include files that would normally be excluded by Github:
theme: jekyll-theme-minimal
include: contributing.md
In reference to the original example, this will allow Github Pages to build a page successfully at the /docs/contributing path.
I'm attempting to set up a basic Jekyll site on github pages. The site in question currently is:
https://kculmback.github.io/kcfeatures-v2/
Here is the repo:
https://github.com/kculmback/kcfeatures-v2
My problem is that the site is not loading images or the css files from my assets folder, even though the link seems to be correct (as far as I can tell).
Example link to image:
kculmback.github.io/kcfeatures-v2/assets/img/Logo.svg (currently not working)
Here is the image in the repo:
github.com/kculmback/kcfeatures-v2/blob/master/assets/img/Logo.svg
This is my first time setting up a Jekyll site but as far as I can tell from everything I've read I've done it all right...
Here is the siteurl/url settings from my _config.yml file:
# Serving
url: "http://kculmback.github.io"
baseurl: "/kcfeatures-v2"
Here is an example of how I wrote the link to CSS file:
<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/app.css">
And here is the resulting link when rendered by Github Pages:
https://kculmback.github.io/kcfeatures-v2/assets/css/app.css
Any help would be greatly appreciated!
The problem is not the url, but what it is excluded in the _config.yml:
exclude:
- "/assets/"
The above line tells Jekyll to exclude directories and files from the conversion.
So the website is being generated without the assets directory, while the urls are ok.
You have to remove assets from the exclude list and it works.
I'm trying to use GitHub pages to host a Doxygen site. Ideally, I'd like to be able to push the generated files and directories to GitHub without having to tweak them at all.
This, however, means that my index.html is in a subfolder of the repository and GitHub Pages isn't picking it up (I get a 404 when I try to access the Pages site). Is there a way to make GitHub recognise that index.html when it's in a subfolder?
It is a project site.
Create a dummy index.html at the root and put this in your header:
<meta http-equiv="refresh" content="0; url=https://repo.github.io/folder/index.html">
Be sure to change the destination URL. This will instantly redirect from index.html to your folder/index.html.
Maybe you want to push a subtree. For instance, let's say you have the build/dist directory and there the Doxygen site is built.
After building, to make sure to commit all changes in that folder, then do the following.
git subtree push --prefix build/dist origin gh-pages
It's important that you don't have anything on the gh-pages branch, on local or origin.
All credit goes to: https://gist.github.com/cobyism/4730490
Initially I also thought of a redirect. But redirects feel like code smells, even HTTP redirects. Although sometimes unavoidable, here may be a cleaner solution, and it is probably what you were looking for.
You now have the option to use the /docs folder of the master branch as the root of your GitHub Pages website.
To use Doxygen and gh-pages, you need to:
Create the file .nojekyll in the root of your gh-pages branch
Make sure you removed .png, .html, and similars from your .gitignore file
And finally, create the index.html file in the root of your project:
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="1;url=html/index.html">
<title>Page Redirection</title>
</head>
<body>
If you are not redirected automatically,
follow the link to the documentation
</body>
</html>
References:
GitHub Pages (github.io) doxygen generated page not found (404)
How to automatically generate doxygen documentation using Travis
Auto-deploying Doxygen documentation to gh-pages with Travis CI
https://help.github.com/categories/github-pages-basics/
Publish Your Project Documentation with GitHub Pages
How to make an introduction page with Doxygen
The answer by David Jacquel is awesome.
But if you're trying to serve your whole SPA personal blog from the /dist or /build folder of GitHub Pages as I do, there's a beautiful dirty hack by Raphael Pedicini.
He suggests that you create a proxy index.html page and custom 404.html page. If your user enters the direct URL of a subpage, e.g. https://example.github.io/blog/, the GitHub Pages server will serve 404.html with scripts that pass the URL as a set of parameters to a proxy index.html, which launches the SPA.
I won't duplicate his code here, as it very well might change over time.
Try transferring your index.html file and all its dependencies into a new repository and then use that repository as a sub-module in you current repository. Currently GitHub Pages expects to find an index.html file in the root of your repository which it can't.
For example, let’s say your current repo is 'test'. You create anew repository say, 'website', transfer your .html and other files which are required to the 'website' repository. Now you need to use 'website' repository as a sub-module inside the 'test' repository.
Mote: in the above schema you only need to use the 'gh-pages' branch-name in your 'website' repository while 'test' can still retain the master branch.
A little example tutorial on Git submodules.
While creating GitHub Pages for my project I was suggested to import existing README.md as the project's homepage. Later, I merged gh-pages with master and ended up with both index.html and README.md.
The "problem" is that the updates to README.md won't affect index.html. Is there any simple way to keep them in sync? Preferably with zero Jekyll knowledge...
Here's what I came up with, in case someone is interested.
Typically I write HTML using Jade preprocessor, and luckily it does support GitHub Flavored Markdown which is the language README.md is written in. So my steps where as following:
Translate index.html generated by GH Pages to Jade. I used online html2jade tool;
Save the output to index.jade;
Locate section block in the resulting markup in index.jade and replace its entire content with:
section
include:md README.md
Run jade index.jade which produces new, automatically generated index.html;
Commit both files to gh-pages.
See example in this commit on GitHub.
I recently wanted to publish my Jekyll site on Github pages, but it seems that putting everything in a subdirectory is giving some issues, even after I change the source to the correct directory.
My structure looks like this:
- site
- src (contains all Jekyll stuff)
- README.md
- GruntFile.js
- ...
Locally my site builds perfectly and when I go to http://localhost:4040 I can see it just nicely, but when I commit this to my Github and visit username.github.io I get a 404, if I go to username.github.io/src I can see part of my site, however all {% include %} are ignored.
In my _config.yml I updated the source: source: ./src, but that doesn't seem to help.
Is there a way to make Github Pages handle subdirectories properly? Basically I want to tell it that my Jekyll site is inside /src, and I want the url to just be username.github.io instead of username.github.io/src
I know i can use the pages branch and commit to there, but I would prefer if it could happen automaticly.
If it helps anyone, I attempted to run Jekyll on GH Pages from a subdir (and modified source) and was banging my head against the wall over these errors:
A file was included in subdir/index.html that is a symlink or does not exist in your _includes directory. For more information, see https://help.github.com/articles/page-build-failed-file-is-a-symlink.
After much searching on this, the definitive answer was right there in the docs:
Configuration Overrides
We override the following _config.yml values, which you are unable to
configure:
safe: true
lsi: false
source: your top-level directory
Keep in mind that if you change the source setting, your pages may not
build correctly. GitHub Pages only considers source files in the
top-level directory of a repository.
I contact Github support and they gave me 2 solutions.
Move all my Jekyll source files to my top-lever directory.
Use a different branch and update it manually each time.