neoneuron.github.io
Personal website based on al-folio
A simple, clean, and responsive Jekyll theme for academics.
Installation
Local setup using Docker (Recommended on Windows)
You need to take the following steps to get al-folio up and running in your local machine:
- First, install docker and docker-compose.
- Then, clone this repository to your machine:
$ git clone [email protected]:<your-username>/<your-repo-name>.git
$ cd <your-repo-name>
Finally, run the following command that will pull a pre-built image from DockerHub and will run your website.
$ docker-compose up
Note that when you run it for the first time, it will download a docker image of size 300MB or so.
Now, feel free to customize the theme however you like (don't forget to change the name!). After you are done, you can use the same command (docker-compose up) to render the webpage with all you changes. Also, make sure to commit your final changes.
To change port number, you can edit
docker-compose.ymlfile.
(click to expand) Build your own docker image:
Note: this approach is only necessary if you would like to build an older or very custom version of al-folio.
Build and run a new docker image using:
$ docker-compose -f docker-local.yml up
If you want to update jekyll, install new ruby packages, etc., all you have to do is build the image again using
--force-recreateargument at the end of previous command! It will download ruby and jekyll and install all ruby packages again from scratch.
Local Setup (Standard)
Assuming you have Ruby and Bundler installed on your system (hint: for ease of managing ruby gems, consider using rbenv), first click Use this template above the file list, create a new repository at github.com:<your-username>/<your-repo-name> from github.com:alshedivat/al-folio and do the following:
$ git clone [email protected]:<your-username>/<your-repo-name>.git
$ cd <your-repo-name>
$ bundle install
$ bundle exec jekyll serve --lsi
Deployment
Deploying your website to GitHub Pages is the most popular option. Starting version v0.3.5, al-folio will automatically re-deploy your webpage each time you push new changes to your repository! :sparkles:
For personal and organization webpages:
- Rename your repository to
<your-github-username>.github.ioor<your-github-orgname>.github.io. - In
_config.yml, seturltohttps://<your-github-username>.github.ioand leavebaseurlempty. - Set up automatic deployment of your webpage (see instructions below).
- Make changes, commit, and push!
- After deployment, the webpage will become available at
<your-github-username>.github.io.
For project pages:
- In
_config.yml, seturltohttps://<your-github-username>.github.ioandbaseurlto/<your-repository-name>/. - Set up automatic deployment of your webpage (see instructions below).
- Make changes, commit, and push!
- After deployment, the webpage will become available at
<your-github-username>.github.io/<your-repository-name>/.
To enable automatic deployment:
- Click on Actions tab and Enable GitHub Actions; do not worry about creating any workflows as everything has already been set for you.
- Go to Settings -> Actions -> General -> Workflow permissions, and give Read and write permissions to GitHub Actions
- Make any other changes to your webpage, commit, and push. This will automatically trigger the Deploy action.
- Wait for a few minutes and let the action complete. You can see the progress in the Actions tab. If completed successfully, in addition to the
masterbranch, your repository should now have a newly builtgh-pagesbranch. - Finally, in the Settings of your repository, in the Pages section, set the branch to
gh-pages(NOT tomaster). For more details, see Configuring a publishing source for your GitHub Pages site.
(click to expand) Manual deployment to GitHub Pages:
If you need to manually re-deploy your website to GitHub pages, go to Actions, click "Deploy" in the left sidebar, then "Run workflow."
(click to expand) Deployment to another hosting server (non GitHub Pages):
If you decide to not use GitHub Pages and host your page elsewhere, simply run:
$ bundle exec jekyll build --lsi
which will (re-)generate the static webpage in the _site/ folder.
Then simply copy the contents of the _site/ foder to your hosting server.
Note: Make sure to correctly set the url and baseurl fields in _config.yml before building the webpage. If you are deploying your webpage to your-domain.com/your-project/, you must set url: your-domain.com and baseurl: /your-project/. If you are deploing directly to your-domain.com, leave baseurl blank.
(click to expand) Deployment to a separate repository (advanced users only):
Note: Do not try using this method unless you know what you are doing (make sure you are familiar with publishing sources). This approach allows to have the website's source code in one repository and the deployment version in a different repository.
Let's assume that your website's publishing source is a publishing-source sub-directory of a git-versioned repository cloned under $HOME/repo/.
For a user site this could well be something like $HOME/<user>.github.io.
Firstly, from the deployment repo dir, checkout the git branch hosting your publishing source.
Then from the website sources dir (commonly your al-folio fork's clone):
$ bundle exec jekyll build --lsi --destination $HOME/repo/publishing-source
This will instruct jekyll to deploy the website under $HOME/repo/publishing-source.
Note: Jekyll will clean $HOME/repo/publishing-source before building!
The quote below is taken directly from the jekyll configuration docs:
Destination folders are cleaned on site builds
The contents of
<destination>are automatically cleaned, by default, when the site is built. Files or folders that are not created by your site will be removed. Some files could be retained by specifying them within the<keep_files>configuration directive.Do not use an important location for
<destination>; instead, use it as a staging area and copy files from there to your web server.
If $HOME/repo/publishing-source contains files that you want jekyll to leave untouched, specify them under keep_files in _config.yml.
In its default configuration, al-folio will copy the top-level README.md to the publishing source. If you want to change this behaviour, add README.md under exclude in _config.yml.
Note: Do not run jekyll clean on your publishing source repo as this will result in the entire directory getting deleted, irrespective of the content of keep_files in _config.yml.
License
The theme is available as open source under the terms of the MIT License.
Originally, al-folio was based on the *folio theme (published by Lia Bogoev and under the MIT license). Since then, it got a full re-write of the styles and many additional cool features.
