I have two different static sites with different designs! I want to run them under 1 Jekyll server.. how to do it?
To be specific: here is my situation:
My github repo has a gh-pages branch. Now, my project needs two different sites (of course running under same root with sub folders).
documentation site - should run at username.github.com/repo/doc/
Testing site - should run at username.github.com/repo/test/
each of these two sites have their own _includes, _layouts, static files etc.. those two are completely different..
How do I setup such a project..
This is simple if you are willing to build the sites locally by running Jekyll first, and then pushing the contents of _site to the respective directories on the gh-pages branch of your repo.
In the github repo called "repo", just create a gh-pages branch with the directories doc and test. Copy the contents of _site generated by running Jekyll on each of your separate Jekyll projects (which can live wherever you want) to doc/ and test/ and voila.
I do not believe you can trick github into running jekyll twice on the same repo to compile the different sites as sub-folders. However, simply by using different layouts in _layouts (pointing to different css files, etc) you can make two completely separate webpages appear as you want them to be -- I don't see why it is strictly necessary (other than simple preference) to maintain them as separate Jekyll projects. (This approach would allow you to just push your changes and let github run Jekyll and build the site).
Related
I am a total programming noob and assume I'm missing something basic.
I forked this repo: https://github.com/colinmorris/tour-of-heroes
Here is the author's page for that repo: https://colinmorris.github.io/tour-of-heroes/
My fork: https://github.com/SmallFryHero/tour-of-heroes
My page based on that fork: https://smallfryhero.github.io/tour-of-heroes/
My page does not load.
I deployed the Github Pages using the gh-pages branch and from the /root folder.
I imported the code into a different web editor, CodeSandBox, and I can get it to run there along with my changes.
What do I need to fix to get it to run on my Github Pages? I added a readme to get the page to build. It seems to be deployed, but doesn't get past the "loading..." step.
Thanks for any help! Sorry for the total noob question.
The issue is that GitHub Pages, by default, use a static site generator called Jekyll under the hood. It basically converts a set of Markdown files into HTML (and provides templating, themes, plugins, and more).
In the case of your repo, which consists exclusively of static assets, Jekyll doesn't do much, but it does exclude the node_modules directory (see logs), which leads to the scripts in there being unavailable to the deployed page.
To fix this, you can indicate that you wish to skip any Jekyll processing and just upload the files as they are; to do so, add an empty file .nojekyll to the root directory in the gh-pages branch, as described in the documentation.
The repo from which you forked was last deployed multiple years ago, and I suspect the Jekyll default configuration back then didn't exclude node_modules yet.
I need to host the documentation of multiple versions of my project (say 1.0, 2.0 and 3.0) and all are active (documentation)branches and we shall keep on adding improvements to all of these.
Is it possible to use GitHub pages for this purpose?
Appreciate any help on this.
This is feasible using Github Actions along with a static site generator (SSG) of your choice such as VuePress, Gatsby, Jekyll etc.
In its simplest form, create a GH action to generate the static site folder of the branch/release, then push the folder to corresponding folder in the branch pointed to by GH pages, say gh-pages. One of the branches/releases should be pushed to root. GitHub Pages Deploy Action can be helpful. Lastly add a dropdown list of versions to your static website pointing to the matching folder. The list of items can be statically maintained or dynamically populated using GitHub API. The selected item depends on the current URL path.
Example:
To provide multi-version docs for software product NotifyBC,
input - docs folder of the product created by VuePress
output - gh-pages branch
GitHub action, with main branch pushed to root of gh-pages branch and releases pushed to version folder
dynamically populated dropdown list implemented in Vue component
rendered site powered by GH pages
You can have a look at gh-pages-multi.
It is a small nodejs tool I wrote to push different versions of docs to subdirectories in a gh-pages branch. It also generates a index.html file listing those subdirectories.
It is fairly easy to integrate in a CI workflow if you want to automate building and pushing the docs.
Also note the "--no-history" option that will prevent bloating the git repo if your docs contain some built files or binary assets.
These other answers over-complicate things. As #jhpratt suggests in the comment, you can just copy the code corresponding to a version of your site you want to deploy to a dir (labelled e.g. v1.0) within the dir that you deploy to gh-pages. You then access the version with https://your-name.github.io/your-repo/v1.0/.
Of course, depending on the type of site you're building you may have to worry about the content of <base href="..."> tag, etc., for each version, but you need to worry about this tag in any case since github pages do not deploy to the url root.
I have a GitHub organization where I publish a webpage from the repository orgname.github.io. Of course, I have several project repositories where I'd like to host documentation about those projects. This is all possible through GitHub Pages.
However, I'm not sure how to synchronize the configuration of the organization page with the project pages. I want the website to look the same whether I'm at
http://orgname.github.io or if I'm at http://orgname.github.io/project.
What can I do to keep the Jekyll-based configuration in sync?
This is the solution we've come up with:
Create a repository to contain the Jekyll configuration, jekyll-website.
Fork/copy the repository to the repository <orgname>.github.io.
In every project, create a git subtree as the docs directory.
Whenever you need to make change to the look/design of the webpage, do it in jekyll-website, then pull those changes into <orgname>.github.io and all the project subtrees. This is a little bit of work whenever you need to make changes to the website, but it gets the job done.
Since the Github pages sites are hosted in the gh-pages branch of their respective repos, they are independent from each other and the project pages.
I'm assuming your content will be unique for each repo, so you're asking about syncing the theme/structure etc, which as far as I know that cannot be synced. I would recommend choosing a Jekyll theme for all of your sites and stick to editing content.
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.
My GitHub org is github.com/Obrary (apologies for not putting the full url, but I don't have enough reputation points for that yet). There, I have 100s of open designs for products. Each is a project. I want each to have a GitHub page for the project.
I created a simple GitHub page for one of the projects. See http://obrary.github.io/Alex-Chair/. The page is created so that I can add it to any projects gh-pages branch and it will work for the new project. To see that in action, http://obrary.github.io/Alexey-Surfboard-Rack/.
Now I want to use this page across all of my open design projects. As I said, there are 100s. So I don't want to just copy and paste the files. Is there a way to make a project that is the 'master template' for all of the projects that I want to associate it to? I'd like to be able to edit the master and have the changes automatically reflected on all the GitHub pages.
Thanks
What's a challenge !
You already have 100's projects site structured on the same templates in 100's separate repositories and you want to share a common design.
Sharing common style-sheets
Just create a repository to host common stylesheets (eg: https://github.com/Obrary/styles. And from every gh-pages, just grab this stylessheets, you then can replicate styles over your entire networks.
Sharing common templates
If you want to share common templates, the only solution is to group all the projects sites under the same repository.
But here you loose the ability to offer the zip download, specific to every project, and the ability (I think) to allow contributor to work in a specific repository.
The ultimate solution
Having a central repository for templates and styles with a rake task that pushes updates to all the projects repositories. This will make Github pages regenerates automatically on every project. Cool!
Let's elaborate a little on this solution.
You have a central repository for all common files needed in your
projects sites. Those files are mainly _includes, _layouts and
_sass folders.
All your projects sites are based on this repository. Their pages,
posts and static files can evolve independently from the central
repository.
Any time you're updating the central repository, a webhook calls
a script on a server. This script can be a rake task or a bash script
or anything you're good at.
The script simply copies files or pulls from central repository and
then push to all projects sites.
Github then will publish automatically.