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.
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 am struggling to figure out why the only thing I see on github page is the read me file.
I followed the instructions to publish to a github page here :
https://abhiverma04.github.io/dummycv/
my repo
https://github.com/abhiverma04/dummycv
Looks like readme.md takes priority over index.html.
You can either make orphan gh-page branch and put all your files (except readme.md) to this branch. Or create /docs folder and copy all your files to the /docs folder except of readme.md. And after this action enable the relevant sourcesetting in GitHub pages as it is described in the GitHub documentation
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 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.
I created a wonderful GitHub Pages website for my little project, and I added some other pages into the gh-pages branch.
My problem is that, everytime I regenerate the website from 'Settings=>Automatic Page Generator', everything is cleaned up and I have to restore the files manually.
Is there a way to prevent, or work around this?
It would have been much better if the Automatic Generator was just overwriting his stuff without removing existing files.
Checkout the gh-pages branch.
mkdir _layouts
move index.html to _layouts
edit _layouts/index.html replace the the inner html of the contents section with {{content}}
make new file index.md
Paste markdown content of automatic page generator into index.md
prepend the following to index.md
---
layout: index
---
create _config.yml
include the following in _config.yml:
markdown: kramdown
kramdown:
auto_ids: true
this step is to match github's markdown syntax
add & commit changes, and then push branch back to github.
Now you can simply edit index.md from the gh-branch in your github source browser and it will update using jekyll automatically and not mess with anything in your gh-branch.
You can also make more items editable in the layout using place holder {{page.varname}} and then adding varname:your text to the header of your index.md.
Well, after some tries I found the solution.
I noticed that the only file changed for my site was the index.html, the rest of the generated site was the same. Inside the index.html there was a <section>content</section> tag that was containing the html generated from the markdown.
So I created two files header.inc and footer.inc, that contained the "static" part for the index page. The content part should have been generated from the README.md file.
I found that there is an API provided by github to render a RAW markdown in raw mode to html.
So, last piece of the puzzle was to obtain a permalink for the README.md of my project, with the RAW content; which I happened to find here.
So I wrote this simple bash script that regenerates the index.html alone, without touching the rest of the site:
#!/bin/sh
PG_DIR=$(dirname $0)
RAW_README_URL=https://raw.github.com/lviggiano/owner/master/README.md
GITHUB_API_URL=https://api.github.com/markdown/raw
cat $PG_DIR/header.inc
curl -s $RAW_README_URL | curl -s --data-binary #- -H 'Content-Type: text/plain' $GITHUB_API_URL
cat $PG_DIR/footer.inc
Then I just launch the script as:
$ cd myproject
$ git checkout gh-pages
$ git pull origin gh-pages:gh-pages
$ ./bin/autogen > index.html
$ git commit -m "updated index.html from latest README.md" index.html
$ git push origin gh-pages:gh-pages
See the implementation details here.
I tested with the "Leap Day" layout; but I suppose it works also for the others.
No, not possible. GitHub wipes the gh-pages repository when you do a "generate". Best you can do is what you are doing now. Another option might be not to use the GitHub page generator to change styles, but to find the source of the styles (they're probably on GitHub somewhere) and manually change them by committing changes (substitute the css files and other minor tweaks)
You can configure Jekyll to skip certain directories with the exclude option.
(Note that Jekyll has a keep_files option -- that is for the files in the destintation directory.)