I'm hosting a site on Github pages, and using Jekyll to generate it.
I added Angular and Lodash to my project using npm, but didn't want to upload 200 odd files to GitHub so I added node_modules to my .gitignore file and just made sure they were added as dependencies within package.json. The problem then becomes that GitHub pages/Jekyll doesn't auto-install the packages when it (Jekyll) generates.
So my question is, how can I use NPM on GitHub pages without actually uploading my node_modules folder into my GitHub repository?
You have two options:
build your site locally
Just generate your static files locally and then upload the final website to Github pages (Github can host non Jekyll websites)
use CI
Implement a script that after uploading your files to the master branch (in Travies for example), it builds your site and push the changes to the gp-pages branch.
According to the GitHub, you can add a _config.yml file to tell Jekyll to "include" the "node_modules" and "vendors" directories.
See:
https://help.github.com/en/articles/configuring-jekyll
Related
I have a static site, built locally by Jekyll, in a /docs folder inside the master branch of my repo, and have set my GH Pages settings to serve from that folder.
However, I keep getting Your site is having problems building: Page build failed. For more information, see https://help.github.com/articles/troubleshooting-github-pages-build-failures.
Some notes:
The repo itself is a Jekyll project, however, as I am using a private submodule GH Pages won't serve this as a Jekyll site, therefore this is why I have compiled the site locally to /docs and set this to be where GH Pages serves from.
The files in /docs are all compiled and just HTML, CSS and JS. No folders or files with _ preceding.
I have added .nojekyll in both the /docs folder and also in the root of the project, just in case.
The error message above is the only information GitHub is returning; no specific error code.
As far as I can tell, this is just a basic static website and GH should have no problem serving it. The only thing I can think is that it's getting confused by the fact that it's inside a jekyll project, but the only fix I can see for that is .nojekyll and that hasn't worked.
Does anyone have any ideas? I'm afraid I can't share the repo as it is a private company repo.
Posting this answer immediately so others may find it useful.
The private submodule breaks the build process, even though the pages site is set to serve from the /docs subfolder. Removing the submodule fixes the issue and serves the site as expected.
http://leongaban.github.io/leongaban-10/ (<- displaying the default github page theme)
Here is my repo with a jekyll blog that works 100% locally, I did create the gh-pages branch. Below is a screenshot of what the blog should look like on my github page:
Do I need to change anything here in my _config.yml?
Site settings
title: Leon Gaban
email: leongaban#gmail.com
description: "Leon Gaban"# this means to ignore newlines until "baseurl:"
baseurl: "" # the subpath of your site, e.g. /blog
url: "http://leongaban.com" # the base hostname & protocol for your site
twitter_username: leongaban
github_username: leongaban
# Build settings
markdown: kramdown
The name of your repository must end in github.com/github.io i.e. rename your https://github.com/leongaban/leongaban-10/ repo to: https://github.com/leongaban/leongaban.github.io
Add this to your _config.yml:
kramdown:
input: GFM
in order to keep the same markdown GitHub will use.
Also, if it is your user website username.github.io it's better move it to a master branch. gh-pages branch is supposed to be applied to project websites only.
Your _site folder is not supposed to be there. It contains the site already build. Normally it's useful for local preview and when you're hosting with a service that doesn't build Jekyll automatically, like an Apache server. Also when you use Jekyll plugins that are not allowed by GitHub, so you choose building the site locally and uploading the static site only to GH.
I see two approaches: weather you remove the _site folder and move your project to the master branch, or you remove the rest of the content and upload to your repo only the content of the _site folder (not the folder itself).
Hope to have helped!
I'm using Jekyll and GitHub Pages to create documentation for projects that live in separate repos that are part of an organization account in GitHub. My team has decided it makes the most sense for the docs to live in each repo alongside the code, so we'll be using a gh-pages branch in each repo.
I will also be setting up a separate gh-pages repo from the organization account to serve as a landing page. I'd like to have all of my jekyll config items live in this repo. What do I need to put in the config file in each of the repos to successfully pull all of the layouts, css/scss, etc. from this central location? Is this even possible?
Here's a visual representation
In a nutshell, I'm trying to have one place where I can make changes to the website formatting files instead of 6.
On Github pages, you can use resources from another repository by using git submodules.
This works well for _layouts and _sass, but sadly not for _includes. This due to the fact that, in Jekyll 2.x, you cannot configure _includes folder path. This has been committed in the current master and will be available as soon as Jekyll 3 is out and used by github pages.
Edit: With Jekyll 3, you can now configure includes_dir: _mydir. See documentation for Jekyll configuration.
An interim solution can be to merge includes in layouts until you're able to configure _includes path. Not so clean, but, as your templates a centralized, it will be easy to refactor.
Howto
1 - create a resources repository
Adding your organization repository as a submodule will pull both resources, post and pages. Not a good way to go because posts and pages will be present in your project blogs.
The better way is to hosts your resources (_includes, _layouts, _sass, css) in a dedicated repository at github.com/userName/resources.
In your _layouts/default.html, dont forget to call you css with :
<link rel="stylesheet" href="{{ "/resources/css/main.css" | prepend: site.baseurl }}">
2 - Project blog Setup
Create a project blog without resources files and add the resources submodule.
git submodule add https://github.com/userName/resources.git
This creates a resources folder in you repository.
Edit your _config.yml and add:
layouts: /resources/_layouts
sass:
sass_dir: /resources/_sass
You can now jekyll serve, it works.
3 - Resources workflow
As your resources are in a submodule, changes in a template or sass file will not be reflected in your blog automatically.
In order to refresh your blog you will have to do this for all your blogs.
git submodule update --remote
git commit -a -m 'resources update'
git push origin gh-pages
After getting feedback from my team, I ended up doing the following:
create new repo that will be the source of the GH-Pages site
add the individual project repos as submodules of this repo
add a script that tells jekyll to pull content from specific folders in the submodules and place them in a temp dir, then use that temp dir as the build source
#remove docs-build-temp folder if it exists
rm -rf ./docs-build-temp
#make temp-content folder
mkdir ./docs-build-temp
#copy content from doc folder in submodules into temp-content folder
cp -R ./submodule1/doc ./docs-build-temp/newdir1
cp -R ./submodule2/doc ./docs-build-temp/newdir2
#tell jekyll the content source
bundle exec jekyll build -s ./docs-build-temp
The script works when run locally and in Travis CI*.
*I set up ssh authentication between my user acct in github and each of the repos in travis to get around the fact that all of them are private. Seems to be working out ok so far.
The documentation of Jekyll tells me, that the _site-directory of a Jekyll site contains the compiled version of the site I have created after running
Jekyll build
Several articles recommend, that I include the _site-directory in my .gitignore-file because "it just contains the compiled version of my site". (that's what some articles recommend. So, I am not sure if I don't understand some concept of Jekyll or some concept of Git.
If the _site-directory contains the compiled version of a site, shouldn't that be the thing that is on the server the provides the final website? I do understand why you put source code on github and what to do with it, but in the case of github pages, Github is not a versioning system but a file hosting system and the file hosting system should host compiled versions of my work to provide it via MyUsername.github.io to users, right?
My question is: shouldn't it be only the _site-directory of my Jekyll website that I deploy to Github because that should be the compiled source code that github provides to users? So, shouldn't I put anything else in the .gitignore-file EXCEPT the _site-directory?
If I got this all wrong: what is the point in compiling my website via
Jekyll build
if I don't use the compiled source code for anything?
Two solutions :
You don't use Jekyll plugins (or only those supported by github pages)
You build your site only if you need to test it locally (jekyll build or jekyll serve). The generated code (in _site) will not be versioned as github pages will generate pages from the sources.
Put _site to .gitignore
Push you sources to github pages
You use Jekyll plugins
In this case, you need to build locally because Github pages cannot do the job with plugins.
Jekyll build locally
Put _site to .gitignore
commit your sources in one branch
commit your _site in another branch
See this post for more explanations.
I think the point where you are confused is that most of the tutorials talk about at least two different repositories.
the source code of your site, this is where you call Jekyll build
the compiled result, this is the one where you put the contents of the _site directory
Then it makes sense to ignore _site in case 1. out of the same reason you normally ignore compilation results: they are not meant to be tracked because they might change between every compilation without changing the source, so you would have to commit after every build although nothing (visible) has changed.
For repository 2. you of course have to update it with the contents of _site from repository 1 after your build.
Having said that you can of course combine 1. and 2. into a single repository by using master for the contents of _site and another branch e.g. source for the project with the Jekyll build files, here ignoring _site and then updating the master branch with the contents of it after changes.
the _site folder is cleared and all files inside are re-generated upon each "jekyll build". tracking a file that is to be removed seems to serve no useful purposes.
if you are thinking to git push your jekyll site to your github repo as a project page (gh-pages), the _site folder again serves no purposes as the jekyll installation at github will generate the _site for you automatically upon your files upload (git push).
the _site folder is useful only for local preview of your jekyll site (typically to be found at localhost:4000 by default).
I believe you might be looking at things the wrong way, It makes sense to ignore _site since every time you jekyll build your _site gets blasted, everything in there gets erased and written again.
So in my own opinion what you would like to push to github is the working directory since it's there where you work and all your changes are being versioned... with the plus of github doing the compiling and automatically building the site.
That being said, I usually keep _site out of my gitignore since I deploy to another hosting service and my deployment framework grabs the github repository and deploys from a particular branch I need the _site to be there.
I've created my own gitbook. looks good locally.
but how shall I integrate it into my github pages? Similar issues here difficulty-in-getting-gitbook-site-to-show-up-in-github-page
I tried that approach as well, but I have problem setting the grunt up, and I also I would like to do that myself before using an integrated tool.
I tried to copy the generated _book folder to my github page folder, but that didn't workout as there are some encoding issues
Similar question here
I had this question because I don't understand github pages, the underlying steps involve
build the _book folder, this is the static content that will be served
create gh-pages branch copy the _book folder content into gh-pages
github will then serve the content
the command gitbook publish will finish all 3 steps. but I am not familiar with grunt as well , as npm install . is a pre-step.