Internal notes for maintaining this site.
How to create a new instance of this site
Create a new project repository on GitHub and give it any name. For instance, the project
described here was named
manuals. This initial setup will be the project’s
master branch. After this is done, clone the new repostitory to your
local computer. If you are new to GitHub here are some basic instructions for creating
and managing GitHub repositories
Download or clone the Jekyll Documentation Theme
from Tom Johnson. Then copy the directory’s content to your new project repository (here
Subsequently, commit and push its entire content to the
master branch on GitHub.
gh-pages branch to your newly created GitHub project repository.
By adding a
gh-pages branch to a GitHub project, one can host from this branch
a web site (here Jekyll site) for a GitHub project repository. The
master branch of this
project contains the source code of the site and its
gh-pages branch the pre-built web
site components. Instruction for setting up a
gh-pages branch for an existing project
are available here.
Edit a page
Built and test site locally
Run following command within the root directory of the project’s git repository
~/Dropbox/Websites/manuals) and then preview the site at the URL
printed to the terminal. Note, all paths are given here relative to this
The built directory of the site is '../doc_outputs/mydoc/designers'. The changes are
committed automatically when previewing the site with 'jekyll serve' or by executing the 'mydoc_*.sh' bash
script(s) located in the root directory of the project.
Edit site in
Edits should be made in the project’s master
branch and then committed from there to the corresponding branch on GitHub.
Sync changes to
Currently, the changes to
../doc_outputs/mydoc/designers need to be synced into the
gh-pages branch of the project repository. The following accomplishes this with
rsync. The last two lines add, commit and push all changes to the
After this the changes should show up in the life version of the web site. Note, prior to
the syncing, one usually wants to shut down the locally running Jekyell server with
Ctrl-c in its terminal window.
Bash script for automation
To automate the above workflow, run the following
buildAll.sh bash script
from the root directory of the repository’s master branch.
Adding a new page
The easiest is usually to copy an existing page in
\mydoc and then make the necessary
changes to its Jekyll front matter section and content.
Next, the new page needs to be registered properly in the sidebar and URL configuration
After this the new page should be viewable in the local preview of your
browser. This requires a running session of
jekyll serve ... in the root
directory of the repository as shown above.
Commit to GitHub
Similar as above add, commit and push changes to the
of the local and remote repositories or just run
Set theme color
Pick you favorite color here, then apply changes at the proper
./css/theme-blue.css. This task can be greatly simplified by using
R markdown integration
(1) Write R markdown vignette (
*.Rmd file) in
./vignettes directory (e.g.
(2) Render vignette to
.html files with
.md file (here
Rbasics.knit.md) to corresponding
.md file in
(4) Remove front matter genereted by R markdown, but leave the one required for Jekyll
(5) Replace chode chunk tags to the ones required by Jekyll Doc Theme
(6) Move images into proper directory and adjust their path in the
Run steps (2)-(6) with one command using the
render() function and the
Usage of custom domain
- Register a domain name with a provider such as GoogleDomains or GoDaddy.
Next, configure the domain settings on your provider’s website to point to GitHub pages. Sample instructions for GoogleDomains and GitHub pages are given on Curtis Larson’s Blog. Note, if you run a web site under the
gh-pages branch of a GitHub project repository then you will still just use
username.github.io. under the CNAME entry (see table below) without appending the name of the project repository. Also adding a dot at the end of this entry is important. The table below is an example how the settings would look like under the
DNS tab on GoogleDomains. The two IP addresses in the first two lines of the table should be the same for all sites hosted on GitHub.
- Subsequently, add the domain name (e.g.
mydomain.org) associated with this entry to the CNAME file in the
gh-pages branch of your GitHub project repository.
- Very important, if you experience any rendering problems on GitHub, check whether the
_config.yml file of your Jekyll site contains a line starting with
baseurl: "...". If so remove this line or the page will not render properly on GitHub.
A favicon is an icon displayed in the web site tabs of a browser or next to the site name in a
bookmark list. The source image can be generted with most graphics programs (e.g. in SVG
format in Inkscape). To generate the final favicon, the image needs to be exported in bitmap format
(e.g. PNG format) to a file. Subsequently, this file is converted to the final
using one of the many favicon generation tools such as FavIcon Generator.
favicon.ico file is then placed into the
images directory of the Jekyll Doc Theme.
Edit this file accordingly.
The fixed sidebar is a nice feature of this theme. However, if there are too many
section entries then it may be desirable to switch contitionally to a floating behavior
depending on the size of the viewport available on a system. This can be achieved by
changing the height value in ‘js/customscripts.js’ to a larger value (e.g. 800 to 1200):
Check differences in directories
One can also double-check by downloading the changes from GitHub and then run