-
Notifications
You must be signed in to change notification settings - Fork 0
Publish your chapter draft with GitHub Pages
July 19, 2021
To see the rendered chapter content live in the browser, you can publish knited content in our /docs folder using GitHub Pages. We'll use this method to share links of our chapter drafts by July 31st.
Below are the steps to publish your content. You can go through these steps at anytime, but will only need to do the first 2 parts once. Any future pushes of content to your fork in your /docs folder will automatically update live on the web. For example, Francois has published the content for his chapter on LiDAR Acquisition and Analysis here, and any further pushes to his fork's /docs folder will automatically be updated at that link.
You will only need to do this step one time.
- In your fork's GitHub repository, click on the tab Settings
- On the left navigation, click Pages
- Make sure your Source is set to main/docs
- Save
After this, you will see a note that your repo is ready to be published at http://<your github username>.github.io/geomatics-textbook/. You may want to keep this link handy. If you go there after these first steps, you will see whatever is currently inside your fork's /docs folder, which might be out of date or not working correctly. That's okay - you will update the content in the next steps.
As you all probably know, knitting will create/update content in your /docs folder. These files make up the static website that GitHub Pages will serve to the web.
The first thing you'll want to do is knit your RMarkdown files in RStudio so they reflect the most recent version of your chapter drafts. Most importantly, this includes your chapter Rmd's, as well as the index.Rmd file.
Some of you have also merged the most recent changes in the original repository with your fork. So, if you are seeing files like 05-network-analysis.Rmd or 02-mapping-data.Rmd in your fork, you should knit those too to compile a fully-functioning book.
Once you have knit your files, verify they are working in RStudio.
Long story short, you will need to tell GitHub Pages that we are not using Jekyll for generating our website pages. You will also only need to do this part one time.
If you're using Terminal or GitBash, you can create a new file called .nojekyll using:
touch docs/.nojekyll
If you're using RStudio, you in the console type:
file.create('docs/.nojekyll')
You don't need to do anything else to this file. It just needs to be present in your /docs folder or future builds of your site may not work correctly.
Once you've verified your knitted content works as expected and have created your .nojekyll file, git add the files to your staging area, git commit the changes, then git push them to your fork.
Verify that the changes have uploaded by heading to your fork in GitHub, and confirming your latest commit message is the one you just created.
Now refresh your browser for http://<your github username>.github.io/geomatics-textbook/ and verify the changes to your hosted site have propagated and everything is working correctly. Sometimes it takes a couple of minutes for the changes to take place, so don't panic if you don't see them right away.