Is it possible to have Jekyll on a single subsection of my website hosted on GitHub? i.e. is it possible to have "example.github.io" be a regular site and "example.github.io/blog" be statically generated by Jekyll?
I believe it's possible to do this by creating another GitHub repo called "blog" and having that repo managed by Jekyll. I'm wondering if it can all be done in one main "example.github.io" repo.
Thanks!
Yes, it's possible. You just have to use the Exclude setting in your _config.yml to tell Jekyll which files and/or folders it should ignore. Similarly, you can also use the Include setting to specifically include files and/or folders.
Configuration Settings / Global Configuration
https://jekyllrb.com/docs/configuration/#global-configuration
Related
Why is languages section not displayed on my github repository?
My Repository is https://github.com/alumuko/vanilla-datetimerange-picker
I found a question GitHub not showing languages used in repository
So I have added ".gitattributes" in my repository like this.
dist/* linguist-documentation=false
But not displayed yet.
All files under dist/ are considered vendor files by Linguist by default. Vendor files are not counted in language statistics. You can see the list of default vendor files in lib/linguist/vendor.yml.
To consider files under dist/ for language statistics, you can add the following to .gitattributes:
dist/* linguist-vendored=false
linguist-documentation=false shouldn't be needed.
Thanks to pchaigno and Robson.
I added
dist/* linguist-vendored=false
into ".gitattributes",
then the problem has been resolved.
You need this line in the .gitattributes:
dist/* linguist-vendored=false
I've forked it here, made that change and now the language share is displayed:
https://github.com/Robson/vanilla-datetimerange-picker
I keep finding piecemeal examples of things that can go into a .github directory on a GitHub repository.
I can see that it is used for GitHub actions and workflow and for Pull request and issue templates, but I can't see a page outlining what you can put in there with ideally some documentation. I also think I've seen a funding example too.
Basically every time I see something you can do there, I think "that's neat I should do that", but other than examples I can't see a way to discover new things other than by example.
Due to the fact that the directory is called .github it seems to defy Google and SO search as well.
On Github, folder .github is just a convention folder used to place Github related stuff inside it. Github handles some of these files even when you place it in root of your project (such as CONTRIBUTING.md, CODE_OF_CONDUCT.md etc). Because Github is constantly bringing in new features, these features are documented on their own, so there is no "all possible files in .github" page. Feel free to place anything that is related to Github specifically inside it.
Some of the most used files in .github folder:
CODE_OF_CONDUCT.md -> How to engage in community and how to behave yourself.
CONTRIBUTING.md -> How to contribute to repo (making pull request, setting development environment...)
LICENSE.md - A software license tells others what they can and can't do with your source code (You should place this at the root of your project since GitHub ignores it in .github folder. You can find this file while browsing other Git hosting services such as GitLab, Bitbucket etc.)
FUNDING.yml -> Supporting a project
ISSUE_TEMPLATE -> Folder that contains a templates of possible issues user can use to open issue (such as if issue is related to documentation, if it's a bug, if user wants new feature etc) P.S. Take a look at tensorflow ISSUE_TEMPLATE
PULL_REQUEST_TEMPLATE.md -> How to make a pull request to project
stale.yml -> Probot configuration to close stale issues. There are many other apps on Github Marketplace that place their configurations inside .github folder because they are related to GitHub specifically.
SECURITY.md -> How to responsibly report a security vulnerability in project
workflows -> Configuration folder containing yaml files for GitHub Actions
CODEOWNERS -> Pull request reviewer rules. More info here.
dependabot.yml -> Configuration options for dependency updates. More info here.
You don't have to create all these files immediately. If there are lot of bugs reported in your project, create ISSUE_TEMPLATE. If several people wants to support you, create FUNDING.yml . You will create more and more files when the need comes.
Github lists all of the files you can use in the documentation page titled Creating a default community health file and the workflows you can add to the .github directory are detailed in the Introduction to GitHub Actions documentation.
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.
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.