About this website

MA2 ACE was created by Luca De Feo and Nicolas Perrin. Its contents are distributed under the Creative Commons 4.0 Attribution-ShareAlike.

How to use/edit this site

This is a static website automatically generated with Jekyll by GitHub Pages. The source code is available on GitHub and you are allowed to use it under the terms of the Creative Commons 4.0 Attribution-ShareAlike.

You are a teacher, a student, or a casual visitor and want to learn how to improve this site, this help page is for you!

Editing pages

You can edit any page by clicking on the  Edit link in the top menu. You can also add new pages by clicking on the  New link.

This will drop you in GitHub’s file editing interface, where you can modify the source code, preview it, and save your changes by giving a short description of what you modified. If you are a collaborator to this website, and have write access to the GitHub repository, your modifications will be published right away. If you do not have write access, you will be asked to fork the repository and make a pull request. See also the next section.

Most of the pages are written in Markdown, which is a textual format for generating formatted text. Markdown syntax is very intuitive, you can get a quick review here or here.

CAVEATS: The Markdown engine used by this site is Kramdown. Its syntax definitions are slightly different form GitHub Flavored Markdown, thus the preview feature in GitHub might not render source as in the final result.

Other reasons why GitHub’s preview may not correspond to the final results are:

Forking the website for your own use

You want to get a copy of the website and its source code to analyze it, or make your own derivative of it, this is very easily done, even if you’re not (yet!) the technical type.

All you need is a GitHub account. Once your account is setup, forking the repository will create your own copy in your GitHub account. Now go to the settings page and rename your repository to username.github.io (replace username by your GitHub user name).

Now you can make changes to your own copy of the site. Edit some files, save the changes, and examine the result. The compiled static site will be served at https://username.github.io/ (replace username by your GitHub user name).

Note: the website will not be compiled when you first fork the repository. If you want your fork to be served on github.io before committing any changes, you will have to create a local clone of your fork, then push. This will not create any new commit, but will force GitHub to compile your copy of the site. In a Unix shell, this is

git clone git@github.com:username/MA2-ace.git
cd MA2-ace
git push

Contributing your changes back to this site

You have forked the repository, made your changes, and now want to contribute them back to the site, but you do not have write access.

Pull requests are GitHub’s standard way of contributing changes back to the original repository. You can make a pull request for this repository, your changes will be reviewed and integrated back once they are accepted.

Working locally

You want to do more than the occasional editing, or you want to deeply modify the code to make your own site. GitHub’s editor and preview are too limited for this, and handling git history via GitHub’s web interface becomes too clumsy at this point. You need to work locally on your computer.

All you need to work locally is a Git client. Clone the repository and start coding right away.

At some point, you will need to preview your work, but pushing to GitHub each time you want to preview is clumsy. Your best option is to install Jekyll and the required dependencies on your machine. It is recommended to install the GitHub pages gem which provides you with the exact same versions used by GitHub to compile your site.

If you already have Ruby ≥2.5.3, the install part should be as easy as

gem install github-pages

Note that you will need Ruby headers (ruby-dev package on Ubuntu) in order to compile C dependencies.

Now you can cd into your local clone of the repository and launch the compilation by

jekyll serve --baseurl ''

Your site will be generated in a _site sub-directory, and served live at http://localhost:4000/. Any changes to the sources will trigger an automatic recompilation!

Have fun coding!

Starting from scratch

This website was created from an empty template at https://github.com/elementsLMS/eLeMentS/. You can start from there if you want to create a website for your own class.

Fork me on GitHub