al-folio

Guide: creating your website with al-folio

In this post, I’ll explain how to setup a website using al-folio. Their github is well-documented, and most of the information here is a distillate of their quickstart page, and their customisation guide. Note that this guide was made with al-folio v1.0.

I. Creating a github repository for your website

I.1 create a github account at https://github.com/
I.2 go to https://github.com/alshedivat/al-folio and click on the top-right Use this template/Create a new repository. Name your repository <github username>.github.io. To deploy the website, the repository needs to be public.
I.3 in the github interface, navigate to Settings → Actions → General → Workflow permissions and turn on Read and write permissions (don’t forget to click Save)

I.4 open _config.yml and fill in the following fields:

  title: blank
  first_name: <your first name>
  last_name: <your last name>
  url: https://<github username>.github.io
  baseurl:

title: blank uses your name as title in the top-right, you can change it to something else if you want. baseurl: should have nothing after the colon.

Once you’ve done this change, commit it to the main branch.

Some basic info about your website repo

_config.yml governs the global configuration for your website

the pages (tabs at the top) of your website are located in _pages/. To customise their position and enable/disable them, modify the header (yaml information delimited by ---): for example:

  layout: page                # tells the backend what layout to use
  permalink: /publications/   # address: <username>.github.io/publications/
  title: publications         # page title
  description: my work        # page description
  nav: true                   # appears in the top navigation bar
  nav_order: 2                # appears in 2nd position on the top bar

Note that a disabled page will still be accessible by typing its address.

II. Deploying the site

II.1 in the github interface, go to the Actions tab and wait until you have a ✅ on all actions for your last commit. (~2 to 5 min)

Note: if your repository is private, the ruby and javascript-typescript jobs will fail.

II.2 navigate to Settings → Pages → Build and deployment: for Source, select Deploy from a branch, then choose the branch gh-pages.

Note: to un-deploy your website, you can choose None in the branch selection in II.2.

III. About page

III.0 The main page of your website is defined in _pages/about.md. In that file, the content written beneath the header is standard Markdown that your can edit as you please.
III.1 change your profile picture by replacing assets/img/prof_pic.jpg. You can also change the path by editing the header in _pages/about.md:
```
  profile:
      image: <path to your image within the repo>
```
III.2 to set up your social links, go to _data/socials.yml. For example:
```
  email: <your email>
  github_username: <github username>
  hal_id: <hal id>
  scholar_userid: <id for google scholar>
```
for a list of compatible entries and how to add custom ones, see the jekyll-socials documentation.

IV. Publications page

Your publications page is defined in _pages/publications and reads automatically the file _data/papers.bib. Some bibtex fields will be rendered as clickable buttons on your publication page. Here’s an example below:

@Article{article_id,
  abbr = {PREPRINT},
  title = {title},
  author = {authors},
  journal = {journal},
  year = {year},
  month = Aug,
  abstract={},
  bibtex_show=true,
  pdf = {https://<username>.github.io/assets/pdf/paper.pdf},
  poster = {https://<username>.github.io/assets/pdf/poster.pdf},
  code = {code_url},
  slides = {https://<username>.github.io/assets/pdf/slides.pdf},
  preview = {preview.png}
}

abbr will be used to create a blue banner next to your paper entry. preview will add an image preview next to your paper. In this example, the file is located at assets/img/publication_preview/preview.png. PDFs are not supported :c

The following entries create a button:

field	button
abstract	shows abstract
bibtex_show	shows .bib entry
pdf	link to pdf
poster	link to poster
code	link to code
slides	link to slides

V. CV

To add your cv to your website, you have 3 options (I chose V.c personally as of the time of writing).

V.a add a PDF in your socials in _data/socials.yml, for example:
```
  cv_pdf: /assets/pdf/cv.pdf
```
V.b use RenderCV by editing _pages/cv.md in the RenderCV format. For more info, also look at the al-folio CV documentation. RenderCV can automatically output a pdf, which is really cool but the format was too constraining for me.
V.c write your CV in a custom page: just edit/create _pages/cv.md and have a header that looks something like:
```
  layout: page
  permalink: /cv/
  title: cv
  nav: true
  nav_order: 4
```

VI. Google search console

To help with the visibility of your website on the internet, you can reference it yourself in the google search console. Create an account or login, then provide your website url. Google will give you a file that looks with <wifi password>.html, add it to the root of your directory, and enable the field enable_google_verification in _config.yml.

Troubleshooting

If you get github action errors that mention prettier, just delete the file .github/workflows/prettier.yml to disable the action. Prettier is a code formatter used for aesthetics, if you really want to use it you can solve most problems by running it locally:
```
  npm install --save-dev --save-exact prettier @shopify/prettier-plugin-liquid
  npx prettier . --check
  npx prettier . --write
```
I got a LOT of errors with the Integrations tests action, these are mainly for contributing to al-folio, so if you also have issues, just delete .github/workflows/unit-tests.yml. If you have an issue on your website, you can just see it on your website.