This webpage project is geared towards an academic audience.
Creation, modification and customization of the template is fairly easy since it powered by Jekyll and Minimal Mistakes.
Note
-
the editable content of the webpage is in the
master
branch, -
the
gh-pages
branch is meant for GitHub Pages to deploy it, -
the webpage
https://<github-username>.github.io
will be publicly available, regardless the repository is public or private.
Two different paths are suggested:
-
Fork the repository.
This will allow you to interact with github.com/CRIStAL-Sigma/cristal-sigma.github.io and github.com/mmistakes/minimal-mistakes repositories (raise issues, get updates, propose pull requests, etc.) based on the fact that you'll share a common history.
a) Rename the repository as
<github-username>.github.io
inSettings/Options/Repository name
.Note: this long history may take some space on the local machine.
-
Create a new repository from the template
The new repository will start with the same files and folders as CRIStAL-Sigma/cristal-sigma.github.io, but with the own fresh history. You will be able to interact with CRIStAL-Sigma/cristal-sigma.github.io only by raising issues.
a) Name the repository as
<github-username>.github.io
,b) Tick the box "Include all branches".
In both cases, make sure to set up GitHub Pages to deploy the site from the gh-pages
branch:
- Go to
Settings/Pages/Source
, - Select the
gh-pages
branch and/ (root)
folder.
At this point you can check the url https://<github-username>.github.io
, it should look like https://cristal-sigma.github.io.
-
Make sure you have
git
installed on the computer, -
Clone the repository on the computer:
cd <directory-of-the-choice> git clone https://github.com/<github-username>/<github-username>.github.io.git
the webpage is powered by Jekyll and Minimal Mistakes. In order to build and serve the site locally the need to install some dependencies.
-
Follow the installation instructions of Jekyll to get
- Ruby,
- Bundler,
- Jekyll.
-
Install the project dependencies (
github-pages
,minimal-mistakes-jekyll
,jekyll-scholar
) stored in theGemfile
file:cd <path-to-github-username.github.io> git checkout master bundle install
cd <path-to-the-directory.github.io>
git checkout master
bundle exec jekyll serve --livereload
Part of the output should look like
...
Auto-regeneration: enabled for '<path-to-the-directory.github.io>'
LiveReload address: http://127.0.0.1:35729
Server address: http://127.0.0.1:4000
Server running... press ctrl-c to stop.
...
A live view of the current state of the webpage is available at http://127.0.0.1:4000.
More specifically,
bundle exec
builds the site and outputs.html
files, stored in the_site
folder,jekyll serve
opens a port to make the site available in a local server, herehttp://127.0.0.1:4000
,--livereload
automatically refreshes the page according to each change made to the source files.
Pages, posts, add images etc., can be created using simple Markdown syntax in .md
files.
Have a look at
- Minimal Mistake's documentation,
- Jekyll's documentation,
- Markdown syntax guide,
- Liquid syntax guide.
Note: Plain HTML can also be used in .md
files.
Fill in the _config.yml
with the meta-data.
Note: any changes made to the _config.yml
file require the site to be rebuilt, see build and serve the site locally.
For this project the "dark
skin is the default, but many other options are available:
- change the
minimal_mistakes_skin: "dark" # "air", "aqua", "contrast", "dark", "default", "dirt", "neon", "mint", "plum" "sunrise"
in the_config.yml
file, - skins are showcased here.
The main/home page of the webpage is defined in the index.md
(or index.html
) file at the root of the project.
This project makes use of the jekyll-scholar plugin to manage bibliographic entries.
- The default
.bib
file is- located at
_bibliography/example.bib
, - set as default in
scholar:
section of the_config.yml
file.
- located at
- The default "Publications" page is
- declared in
_pages/publications.md
, - set as a webpage page in
_data/navigation.yml
.
- declared in
- Configuration options of the bibliography can be passed in the
scholar:
section of the_config.yml
file, see also jekyll-scholar's documentation.
Buttons with links will appear for references having non empty fields
@type{bib-key
...
url = {}
arxivid = {}
code = {<link-to-code-repository>}
video = {<link-to-video>}
...
}
Additionally, if you store poster and slides files as /assets/pds/<bib-key>_poster.pdf
or /assets/pds/<bib-key>_slides.pdf
the corresponding buttons will also be displayed.
The webpage https://<github-username>.github.io
is deployed by GitHub Pages from the remote gh-pages
branch (set up as the source branch for GitHub Pages in set up the GitHub repository).
However, this project uses the jekyll-scholar
plugin to render bibliography contents, which is incompatible with the direct GitHub Pages workflow.
Every time you push changes to the master
branch, the jekyll-action automatically takes care of
- building the webpage,
- pushing the relevant content to the
gh-pages
branch.
Finally, GitHub Pages automatically deploys the webpage at https://<github-username>.github.io
.
See also .github/workflows/main.yml to see how the action is triggered and parametrized.
The webpage built source files (content of the _site
folder) can be pushed to the gh-pages
branch so that GitHub Pages deploys it automatically.
Note: The size of the repo may grow rapidly since most of the files will be duplicated (files at the root of the project and in site
).
To do this (see also the GitHub gist)
-
Make sure
_site
is not listed in the.gitignore
file -
Save and commit the last changes
git add _site/\* git commit -m "<my-message>"
-
Push to the remote
gh-pages
branchgit push origin `git subtree split --prefix _site master`:gh-pages --force
GitHub Pages will automatically deploys the webpage from the source files you've pushed on the
gh-pages
branch. -
That's it! You can check the results at
https://<github-username>.github.io
Note: you may need to clean some of the browser's navigation data like cache or cookies to see the changes online.