-
Notifications
You must be signed in to change notification settings - Fork 30
Website Maintenance Tips
sudo apt update && sudo apt install -y git ruby-dev libffi-dev libz-dev libtool build-essential
sudo gem install bundler
Inside the website source directory:
bundle install
mkdir -p ~/workspace && cd ~/workspace && rm -rf ipop-project.github.io
git clone https://github.com/ipop-project/ipop-project.github.io.git
cd ipop-project.github.io
git checkout source
rm -rf _site
rm -rf .git/modules/wiki
rm -rf wiki
git submodule add https://github.com/ipop-project/ipop-project.github.io.wiki.git wiki
Update the website and apply the desired changes.
mkdir -p _site/wiki && touch _site/wiki/_Sidebar.html
bundle exec jekyll build
JEKYLL_ENV=production bundle exec jekyll serve
rm -rf ~/workspace/_site
cp -r _site ~/workspace
rm -rf wiki
git add .
git commit -m "Update Website"
git push
git checkout master
rm -r *
cp -r ~/workspace/_site/* .
git add .
git commit -m "Update Website"
git push
- Source Files Including Markdown Files for Pages: source Branch
- Static Pages Built by Jekyll: master Branch
- The website needs to be loaded from the branch with static pages since there are some unsupported plugins used on the website which will not build-able online by GitHub Jekyll. We have to build the website locally and then upload the static pages to the GitHub.
CNAME file in the root of the repo contains the domain name, ipop-project.org in this case. This should be set just for the main repo, https://github.com/ipop-project/ipop-project.github.io in this case, not other forks on GitHub. Otherwise, it throws an error while building the website on the GitHub.
With the current configuration set in the _config.yml for the url and baseurl, the website should be displayed fine locally and on the main addresses, ipop-project.github.io and ipop-project.org, not on the forked repos like https://vahid-dan.github.io/ipop-project.github.io/. There, the styles won't get loaded and the URLs will be set to the main repo.
To update the website integrated wiki based on the GitHub Wiki and also the first time after cloning the repo, the Wiki submodule should be updated. Otherwise, the wiki pages will be missing on the website.
In the main repo, source branch:
git rm -rf --cached wiki/
rm -rf .git/modules/wiki
rm -rf wiki
git submodule add https://github.com/ipop-project/ipop-project.github.io.wiki.git wiki
In the main repo:
git submodule add https://github.com/ipop-project/ipop-project.github.io.wiki.git wiki
git commit -m "Wiki Added as a Submodule"Delete the relevant section from the .gitmodules file.
Stage the .gitmodules changes git add .gitmodules.
Delete the relevant section from .git/config.
Run git rm -rf --cached wiki/.
Run rm -rf .git/modules/wiki.
Commit git commit -m "Wiki Submodule Removed".
Delete the now untracked submodule files rm -rf wiki.
sudo gem install bundler
sudo apt install ruby-dev
In the main repo, source branch:
bundle install
touch _site/wiki/_Sidebar.html
bundle exec jekyll build
JEKYLL_ENV=production bundle exec jekyll serve
Use Jekyll Optional Front Matter plugin.
In order to make relative links in wiki pages work correctly inside Jekyll website, remove the / from the end of the following line in _config.yml:
permalink: /:categories/:title/This technique would allow you to set up redirects for your pages without resorting to any plugin. All you need to do is create a layout named redirected.html in your _layouts folder. The content of this layout would be as shown below:
<!DOCTYPE html>
<html>
<head>
<link rel="canonical" href="{{ page.redirect_to }}"/>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta http-equiv="refresh" content="0;url={{ page.redirect_to }}" />
</head>
<body>
<a href="{{ page.redirect_to }}">Redirecting ...</a>
<script>location='{{ page.redirect_to }}'</script>
</body>
</html>Once you have this layout ready, then to set up redirect from any page, all you need to do is specify redirected as your layout in its YAML front matter and specify the destination in redirect_to as shown below. in wiki.md:
---
layout: redirected
sitemap: false
permalink: /wiki/
redirect_to: Home
---Note that, I have also included sitemap: false in the front matter as I don’t want the redirected pages to be included in the sitemap.
Note: This plugin doesn't work on GitHub. So we have to build it locally and then upload the _site directory to gh-pages branch and change the GitHub settings so that it loads the website from gh-pages branch instead of master branch.
To make it appear in all the wiki pages automatically, add toc: true to the wiki layout settings defaults in _config.yml:
# wiki
- values:
toc: trueRemove default layout and sidebar from _Sidebar.html. Exclude everything except {{ content }}. Check the default.html content.
use jekyll-include-absolute-plugin to add support for including files outside the _includes directory.
Note: This plugin doesn't work on GitHub. So we have to build it locally and then upload the _site directory to gh-pages branch and change the GitHub settings so that it loads the website from gh-pages branch instead of master branch.
Include _Sidebar.md to the Jekyll include list in _config.yml:
include:
- _SidebarInsert the sidebar in the wiki template wiki.html. Check the file content.
Add proper styles to main.scss:
.layout--wiki .sidebar .nav__list strong {
display: block;
margin: 0.5rem 0;
padding: 0.5rem 0;
font-family: -apple-system,".SFNSText-Regular","San Francisco","Roboto","Segoe UI","Helvetica Neue","Lucida Grande",Arial,sans-serif;
font-weight: bold;
text-transform: uppercase;
border-bottom: 1px solid #f2f3f3;
}
.layout--wiki .sidebar .wiki-top-links {
font-size: .775em;
}
.layout--wiki .sidebar li {
font-size: .85em;
}There is a line in the _layouts/wiki.html to include the wiki sidebar, _site/wiki/_Sidebar.html:
If the file doesn't exist, Jekyll will throw an error while building the website. It usually happens when you want to delete the old generated files in _site directory and re-build them. This line will always be checked even if it is in a condition that is not TRUE.
A workaround would be to create an empty file at that path manually and after a successful Jekyll build, run the build or serve command for the second time to include the wiki sidebar:
touch _site/wiki/_Sidebar.html
bundle exec jekyll build
JEKYLL_ENV=production bundle exec jekyll serve
- Follow the page format from Install and Run IPOP on Ubuntu and Raspberry Pi.
- Every wiki page should start with a Header 1 title. It would be the title of the respective page on the website. Otherwise, the page won't have a title on the website.
- There should be a blank line before each table. Otherwise, the table won't render correctly on the website. That won't affect the table view on the wiki, though.
- Avoid using anything that looks like Liquid objects and tags on the wiki. Those will cause an error while building the website. If you need more info, take a look at the Liquid Introduction.
- The website will be automatically updated according to the wiki updates every day.