Update README
This commit is contained in:
Maruan Al-Shedivat
parent
938b22e132
commit
738791a3f9
25
CONTRIBUTING.md
Normal file
25
CONTRIBUTING.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Contributing to al-folio
|
||||
Thank you for considering to contribute to al-folio!
|
||||
|
||||
|
||||
## Pull Requests
|
||||
We welcome your pull requests (PRs).
|
||||
For minor fixes (e.g., documentation improvements), feel free to submit a PR directly.
|
||||
If you would like to implement a new feature or a bug, please make sure you (or someone else) has opened an appropriate issue first; in your PR, please mention the issue it addresses.
|
||||
|
||||
|
||||
## Issues
|
||||
We use GitHub issues to track bugs and feature requests.
|
||||
Before submitting an issue, please make sure:
|
||||
|
||||
1. You have read [the FAQ section](https://github.com/alshedivat/al-folio#faq) of the README and your question is NOT addressed there.
|
||||
2. You have done your best to ensure that your issue is NOT a duplicate of one of [the previous issues](https://github.com/alshedivat/al-folio/issues).
|
||||
3. Your issue is either a bug (unexpected/undesirable behavior) or a feature request.
|
||||
If it is just a question, please ask it on [gitter](https://gitter.im/alshedivat/al-folio).
|
||||
|
||||
When submitting an issue, please make sure to use the appropriate template.
|
||||
|
||||
|
||||
## License
|
||||
By contributing to al-folio, you agree that your contributions will be licensed
|
||||
under the LICENSE file in the root directory of the source tree.
|
||||
2
LICENSE
2
LICENSE
@ -1,6 +1,6 @@
|
||||
The MIT License (MIT)
|
||||
|
||||
Copyright (c) 2018 Maruan Al-Shedivat.
|
||||
Copyright (c) 2020 Maruan Al-Shedivat.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
||||
this software and associated documentation files (the "Software"), to deal in
|
||||
|
||||
202
README.md
202
README.md
@ -5,22 +5,20 @@
|
||||
[](https://github.com/alshedivat/al-folio/blob/master/LICENSE)
|
||||
[](https://gitter.im/alshedivat/al-folio?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
|
||||
A simple and clean [Jekyll](https://jekyllrb.com/) theme for academics.
|
||||
A simple, clean, and responsive [Jekyll](https://jekyllrb.com/) theme for academics.
|
||||
|
||||
[](https://alshedivat.github.io/al-folio/)
|
||||
[](https://alshedivat.github.io/al-folio/)
|
||||
|
||||
Originally, **al-folio** was based on the [\*folio theme](https://github.com/bogoli/-folio) (published by [Lia Bogoev](http://liabogoev.com) and under the MIT license).
|
||||
Since then, it got a full re-write of the styles and many additional cool features.
|
||||
The emphasis is on whitespace, transparency, and academic usage: [theme demo](https://alshedivat.github.io/al-folio/).
|
||||
|
||||
## Getting started
|
||||
|
||||
For more about how to use Jekyll, check out [this tutorial](https://www.taniarascia.com/make-a-static-website-with-jekyll/).
|
||||
Why Jekyll? Read this [blog post](https://karpathy.github.io/2014/07/01/switching-to-jekyll/)!
|
||||
|
||||
|
||||
### Installation
|
||||
|
||||
Assuming you have [Ruby](https://www.ruby-lang.org/en/downloads/) and [Bundler](https://bundler.io/) installed on your system (*hint: for ease of managing ruby gems, consider using [rbenv](https://github.com/rbenv/rbenv)*), first fork the theme from `github.com:alshedivat/al-folio` to `github.com:<your-username>/<your-repo-name>` and do the following:
|
||||
Assuming you have [Ruby](https://www.ruby-lang.org/en/downloads/) and [Bundler](https://bundler.io/) installed on your system (*hint: for ease of managing ruby gems, consider using [rbenv](https://github.com/rbenv/rbenv)*), first [fork](https://guides.github.com/activities/forking/) the theme from `github.com:alshedivat/al-folio` to `github.com:<your-username>/<your-repo-name>` and do the following:
|
||||
|
||||
```bash
|
||||
$ git clone git@github.com:<your-username>/<your-repo-name>.git
|
||||
@ -43,17 +41,31 @@ Using `master` for deployment is a convention for [user and organization pages](
|
||||
**Note:** when deploying your user or organization page, make sure the `_config.yml` has `url` and `baseurl` fields as follows.
|
||||
|
||||
```
|
||||
url: # should be empty
|
||||
url: # should be empty
|
||||
baseurl: # should be empty
|
||||
```
|
||||
|
||||
### Usage
|
||||
|
||||
Note that `_pages/about.md` is built to index.html in the published site. There is therefore no need to have a separate index page for the project. If an index page does exist in the root directory then this will prevent `_pages/about.md` from being added to the built site.
|
||||
### Upgrading from a previous version
|
||||
|
||||
If you installed **al-folio** as described above, you can upgrade to the latest version as follows:
|
||||
|
||||
```bash
|
||||
# Assuming the current directory is <your-repo-name>
|
||||
$ git remote add upstream https://github.com/alshedivat/al-folio.git
|
||||
$ git fetch upstream
|
||||
$ git rebase upstream/v0.3
|
||||
```
|
||||
|
||||
If you have extensively customized a previous version, it might be trickier to upgrade.
|
||||
You can still follow the steps above, but `git rebase` may result in merge conflicts that must be resolved.
|
||||
See [git rebase manual](https://help.github.com/en/github/using-git/about-git-rebase) and how to [resolve conflicts](https://help.github.com/en/github/using-git/resolving-merge-conflicts-after-a-git-rebase) for more information.
|
||||
If rebasing is too complicated, we recommend to re-install the new version of the theme from scratch and port over your content and changes from the previous version manually.
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
#### Ergonomic Publications
|
||||
### Publications
|
||||
|
||||
Your publications page is generated automatically from your BibTex bibliography.
|
||||
Simply edit `_bibliography/papers.bib`.
|
||||
@ -61,26 +73,47 @@ You can also add new `*.bib` files and customize the look of your publications h
|
||||
|
||||
Keep meta-information about your co-authors in `_data/coauthors.yml` and Jekyll will insert links to their webpages automatically.
|
||||
|
||||
#### Collections
|
||||
This Jekyll theme implements collections to let you break up your work into categories.
|
||||
The example is divided into news and projects, but easily revamp this into apps, short stories, courses, or whatever your creative work is.
|
||||
<p align="center"><img src="assets/img/publications-screenshot.png" width=800></p>
|
||||
|
||||
> To do this, edit the collections in the `_config.yml` file, create a corresponding folder, and create a landing page for your collection, similar to `_pages/projects.md`.
|
||||
|
||||
Two different layouts are included: the blog layout, for a list of detailed descriptive list of entries, and the projects layout.
|
||||
The projects layout overlays a descriptive hoverover on a background image.
|
||||
If no image is provided, the square is auto-filled with the chosen theme color.
|
||||
Thumbnail sizing is not necessary, as the grid crops images perfectly.
|
||||
### Collections
|
||||
|
||||
#### Theming
|
||||
Six beautiful theme colors have been selected to choose from.
|
||||
The default is purple, but quickly change it by editing `$theme-color` variable in the `_sass/variables.scss` file (line 72).
|
||||
Other color variables are listed there, as well.
|
||||
This Jekyll theme implements `collections` to let you break up your work into categories.
|
||||
The theme comes with two default collections: `news` and `projects`.
|
||||
Items from the `news` collection are automatically displayed on the home page.
|
||||
Items from the `projects` collection are displayed on a responsive grid on projects page.
|
||||
|
||||
<p align="center"><img src="assets/img/projects-screenshot.png" width=700></p>
|
||||
|
||||
You can easily create your own collections, apps, short stories, courses, or whatever your creative work is.
|
||||
To do this, edit the collections in the `_config.yml` file, create a corresponding folder, and create a landing page for your collection, similar to `_pages/projects.md`.
|
||||
|
||||
|
||||
### Layouts
|
||||
|
||||
**al-folio** comes with stylish layouts for pages and blog posts.
|
||||
|
||||
#### The iconic style of Distill
|
||||
|
||||
The theme allows you to create blog posts in the [distill.pub](https://distill.pub/) style:
|
||||
|
||||
<p align="center"><a href="https://alshedivat.github.io/al-folio/blog/2018/distill/" target="_blank"><img src="assets/img/distill-screenshot.png" width=700></a></p>
|
||||
|
||||
For more details on how to create distill-styled posts using `<d-*>` tags, please refer to [the example](https://alshedivat.github.io/al-folio/blog/2018/distill/).
|
||||
|
||||
#### Full support for math & code
|
||||
|
||||
**al-folio** supports fast math typesetting through [KaTeX](https://katex.org/) and code syntax highlighting using [GitHub style](https://github.com/jwarby/jekyll-pygments-themes):
|
||||
|
||||
<p align="center">
|
||||
<a href="https://alshedivat.github.io/al-folio/blog/2015/math/" target="_blank"><img src="assets/img/math-screenshot.png" width=450></a>
|
||||
<a href="https://alshedivat.github.io/al-folio/blog/2015/code/" target="_blank"><img src="assets/img/code-screenshot.png" width=450></a>
|
||||
</p>
|
||||
|
||||
#### Photos
|
||||
Photo formatting is made simple using rows of a 3-column system.
|
||||
Make photos 1/3, 2/3, or full width.
|
||||
Easily create beautiful grids within your blog posts and projects pages:
|
||||
|
||||
Photo formatting is made simple using [Bootstrap's grid system](https://getbootstrap.com/docs/4.4/layout/grid/).
|
||||
Easily create beautiful grids within your blog posts and project pages:
|
||||
|
||||
<p align="center">
|
||||
<a href="https://alshedivat.github.io/al-folio/projects/1_project/">
|
||||
@ -88,35 +121,112 @@ Easily create beautiful grids within your blog posts and projects pages:
|
||||
</a>
|
||||
</p>
|
||||
|
||||
#### Code Highlighting
|
||||
This theme implements Jekyll's built in code syntax highlighting with Pygments.
|
||||
Just use the liquid tags `{% highlight python %}` and `{% endhighlight %}` to delineate your code:
|
||||
|
||||
<p align="center">
|
||||
<a href="https://alshedivat.github.io/al-folio/blog/2015/code/">
|
||||
<img src="assets/img/code-screenshot.png" width="75%">
|
||||
</a>
|
||||
</p>
|
||||
### Other features
|
||||
|
||||
#### Theming
|
||||
Six beautiful theme colors have been selected to choose from.
|
||||
The default is purple, but you can quickly change it by editing `$theme-color` variable in the `_sass/variables.scss` file.
|
||||
Other color variables are listed there as well.
|
||||
|
||||
#### Social media previews
|
||||
The al-folio theme optionally supports preview images on social media.
|
||||
To enable this functionality you will need to set `serve_og_meta` to `true` in
|
||||
your `_config.yml`. Once you have done so, all your site's pages will include
|
||||
Open Graph data in the HTML head element.
|
||||
**al-folio** supports preview images on social media.
|
||||
To enable this functionality you will need to set `serve_og_meta` to `true` in your `_config.yml`.
|
||||
Once you have done so, all your site's pages will include Open Graph data in the HTML head element.
|
||||
|
||||
You will then need to configure what image to display in your site's social media previews.
|
||||
This can be configured on a per-page basis, by setting the `og_image` page variable.
|
||||
If for an individual page this variable is not set, then the theme will fall back to a site-wide `og_image` variable, configurable in your `_config.yml`.
|
||||
In both the page-specific and site-wide cases, the `og_image` variable needs to hold the URL for the image you wish to display in social media previews.
|
||||
|
||||
You will then need to configure what image to display in your site's social
|
||||
media previews. This can be configured on a per-page basis, by setting the
|
||||
`og_image` page variable. If for an individual page this variable is not set,
|
||||
then the theme will fall back to a site-wide `og_image` variable, configurable
|
||||
in your `_config.yml`. In both the page-specific and site-wide cases, the
|
||||
`og_image` variable needs to hold the URL for the image you wish to display in
|
||||
social media previews.
|
||||
|
||||
## Contributing
|
||||
|
||||
Feel free to contribute new features and theme improvements by sending a pull request.
|
||||
Style improvements and bug fixes are especially welcome.
|
||||
Contributions to al-folio are very welcome!
|
||||
Before you get started, please take a look at [the guidelines](CONTRIBUTING.md).
|
||||
|
||||
If you would like to improve documentation, add your webpage to the list below, or fix a minor inconsistency or bug, please feel free to send a PR directly to `master`.
|
||||
For more complex issues/bugs or feature requests, please open an issue using the appropriate template.
|
||||
|
||||
|
||||
## Users of al-folio
|
||||
|
||||
The community of **al-folio** users is growing!
|
||||
Academics around the world use this theme for their homepages, blogs, lab pages, as well as webpages for courses, workshops, conferences, meetups, and more.
|
||||
Check out the community webpages below.
|
||||
Feel free to add your own page(s) by sending a PR.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>Academics</td>
|
||||
<td>
|
||||
<a href="http://maruan.alshedivat.com" target="_blank">★</a>
|
||||
<a href="https://maithraraghu.com" target="_blank">★</a>
|
||||
<a href="http://platanois.org" target="_blank">★</a>
|
||||
<a href="https://otiliastr.github.io" target="_blank">★</a>
|
||||
<a href="https://www.maths.dur.ac.uk/~sxwc62/" target="_blank">★</a>
|
||||
<a href="http://jessachandler.com/" target="_blank">★</a>
|
||||
<a href="https://mayankm96.github.io/" target="_blank">★</a>
|
||||
<a href="https://markdean.info/" target="_blank">★</a>
|
||||
<a href="https://kakodkar.github.io/" target="_blank">★</a>
|
||||
<a href="https://sahirbhatnagar.com/" target="_blank">★</a>
|
||||
<a href="https://spd.gr/" target="_blank">★</a>
|
||||
<a href="https://jay-sarkar.github.io/" target="_blank">★</a>
|
||||
<a href="https://aborowska.github.io/" target="_blank">★</a>
|
||||
<a href="https://aditisgh.github.io/" target="_blank">★</a>
|
||||
<a href="https://alexhaydock.co.uk/" target="_blank">★</a>
|
||||
<a href="https://alixkeener.net/" target="_blank">★</a>
|
||||
<a href="https://andreea7b.github.io/" target="_blank">★</a>
|
||||
<a href="https://rishabhjoshi.github.io/" target="_blank">★</a>
|
||||
<a href="https://sheelabhadra.github.io/" target="_blank">★</a>
|
||||
<a href="https://giograno.me/" target="_blank">★</a>
|
||||
<a href="https://immsrini.github.io/" target="_blank">★</a>
|
||||
<a href="https://apooladian.github.io/" target="_blank">★</a>
|
||||
<a href="https://chinmoy-dutta.github.io/" target="_blank">★</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Labs</td>
|
||||
<td>
|
||||
<a href="https://www.haylab.caltech.edu/" target="_blank">★</a>
|
||||
<a href="https://sjkimlab.github.io/" target="_blank">★</a>
|
||||
<a href="https://systemconsultantgroup.github.io/scg-folio/" target="_blank">★</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Courses</td>
|
||||
<td>
|
||||
<a href="https://sailinglab.github.io/pgm-spring-2019/" target="_blank">CMU PGM 2019</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Conferences/workshops</td>
|
||||
<td>
|
||||
ML Retrospectives (<a href="https://ml-retrospectives.github.io/neurips2019/" target="_blank">NeurIPS 2019</a>, <a href="https://ml-retrospectives.github.io/icml2020/" target="_blank">ICML 2020</a>)
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
## FAQ
|
||||
|
||||
Here are some frequently asked questions.
|
||||
If you have a different question, please ask on [gitter](https://gitter.im/alshedivat/al-folio).
|
||||
|
||||
1. **Q:** When I preview my website locally everything looks great, but when I deploy it on GitHub bibliography Liquid tags are not recognized.
|
||||
How do I fix this? <br>
|
||||
**A:** GitHub Pages rendering does not support certain Jekyll plugins, and `jekyll-scholar` that we use to render bibliography is one of them. Please make sure you deploy your website to GitHub using `bin/deploy` script that circumvents the issue.
|
||||
|
||||
2. **Q:** When I deploy my fork of al-folio, it says `Deployed successfully!`
|
||||
But when I open `<my-github-username>.github.io`, I get `Page not found (404)` error.
|
||||
How do I fix this? <br>
|
||||
**A:** For personal webpages, please run `bin/deploy --user`.
|
||||
(See also relevant past issues: [#5](https://github.com/alshedivat/al-folio/issues/5), [#49](https://github.com/alshedivat/al-folio/issues/49), [#86](https://github.com/alshedivat/al-folio/issues/86).)
|
||||
|
||||
|
||||
## License
|
||||
|
||||
The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
|
||||
|
||||
Originally, **al-folio** was based on the [\*folio theme](https://github.com/bogoli/-folio) (published by [Lia Bogoev](http://liabogoev.com) and under the MIT license).
|
||||
Since then, it got a full re-write of the styles and many additional cool features.
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
|
||||
body {
|
||||
padding-bottom: 70px;
|
||||
color: $text-color;
|
||||
}
|
||||
|
||||
body.fixed-top-nav {
|
||||
|
||||
@ -32,4 +32,4 @@ $grey-color-dark: darken($grey-color, 25%);
|
||||
$theme-color: $purple-color;
|
||||
|
||||
$link-color: $theme-color;
|
||||
$text-color: #111111 !default;
|
||||
$text-color: #111 !default;
|
||||
|
||||
BIN
assets/img/al-folio-preview.png
Normal file
BIN
assets/img/al-folio-preview.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 800 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 47 KiB After Width: | Height: | Size: 182 KiB |
BIN
assets/img/distill-screenshot.png
Normal file
BIN
assets/img/distill-screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 186 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 595 KiB |
BIN
assets/img/math-screenshot.png
Normal file
BIN
assets/img/math-screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 188 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.8 MiB After Width: | Height: | Size: 950 KiB |
BIN
assets/img/projects-screenshot.png
Normal file
BIN
assets/img/projects-screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 842 KiB |
BIN
assets/img/publications-screenshot.png
Normal file
BIN
assets/img/publications-screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 211 KiB |
Loading…
Reference in New Issue
Block a user