silva
/
new_site
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated README to explictly tell how to proceed on fresh install (#1993) 

Updated README to explicitly tell how to proceed on creating your own
version based on this template. Also removed the video tutorial since it
was for an older version, recommending to fork the repo and it was
missing the `--lsi` parameter from jekyll command. Also was not using
docker, the current recommended way.

---------

Signed-off-by: George Araújo <george.gcac@gmail.com>
This commit is contained in:
George 2023-12-18 10:59:08 -03:00 committed by GitHub
parent 36e6ff8705
commit 1fa3febcc7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
README.md
View File

@ -175,6 +175,7 @@ Workshop on Diffusion Models (NeurIPS: <a href="https://diffusionworkshop.github
## Table Of Contents ## Table Of Contents
- [al-folio](#al-folio)
- [User community](#user-community) - [User community](#user-community)
- [Lighthouse PageSpeed Insights](#lighthouse-pagespeed-insights) - [Lighthouse PageSpeed Insights](#lighthouse-pagespeed-insights)
- [Table Of Contents](#table-of-contents) - [Table Of Contents](#table-of-contents)
@ -186,6 +187,7 @@ Workshop on Diffusion Models (NeurIPS: <a href="https://diffusionworkshop.github
- [Upgrading from a previous version](#upgrading-from-a-previous-version) - [Upgrading from a previous version](#upgrading-from-a-previous-version)
- [FAQ](#faq) - [FAQ](#faq)
- [Features](#features) - [Features](#features)
- [CV](#cv)
- [Publications](#publications) - [Publications](#publications)
- [Collections](#collections) - [Collections](#collections)
- [Layouts](#layouts) - [Layouts](#layouts)
@ -210,21 +212,24 @@ Why Jekyll? Read [Andrej Karpathy's blog post](https://karpathy.github.io/2014/0
### Installation ### Installation
For a hands-on walkthrough of al-folio installation, check out [this cool video tutorial](https://www.youtube.com/watch?v=g6AJ9qPPoyc) by one of the community members! 🎬 🍿 The recommended approach for using **al-folio** is to first create your own site using the template with as few changes as possible, and only when it is up and running customize it however you like. This way it is easier to pinpoint what causes a potential issue in case of a bug. The minimum steps required to create your own site are:
The preferred way of using this template is by clicking in [Use this template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) above the file list. 1. Create a new repository using this template. For this, click on `Use this template -> Create a new repository` above the file list. If you plan to upload your site to `<your-github-username>.github.io`, note that the name of your repository MUST BE `<your-github-username>.github.io` or `<your-github-orgname>.github.io`, as stated in the [GitHub pages docs](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites).
Then, create a new repository at `github.com:<your-username>/<your-repo-name>`. If you plan to upload your site to `<your-github-username>.github.io`, 2. In this new repository, go to `Settings -> Actions -> General -> Workflow permissions` and give `Read and write permissions` to GitHub Actions.
note that the name of your repository must be `<your-github-username>.github.io` or `<your-github-orgname>.github.io`, as stated in the [GitHub pages docs](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites). 3. Open file `_config.yml`, set `url` to `https://<your-github-username>.github.io` and leave `baseurl` **empty**.
For more information on how to deploy your site, check the [Deployment](#deployment) section below. After you created your new repository, just download it to your machine: 4. Finally, in the repository page go to `Settings -> Pages -> Build and deployment`, make sure that `Source` is set to `Deploy from a branch` and set the branch to `gh-pages` (NOT to master).
5. Wait until the GitHub actions finish, then simply navigate to `https://<your-github-username>.github.io` in your browser. At this point you should see a copy of the theme's demo website.
After everything is set up, you can download the repository to your machine and start customizing it. To do so, run the following commands:
```bash ```bash
$ git clone git@github.com:<your-username>/<your-repo-name>.git $ git clone git@github.com:<your-username>/<your-repo-name>.git
$ cd <your-repo-name>
``` ```
--- ---
#### Local setup using Docker (Recommended) #### Local setup using Docker (Recommended)
Using Docker to install Jekyll and Ruby dependencies is the easiest way. Using Docker to install Jekyll and Ruby dependencies is the easiest way.
You need to take the following steps to get `al-folio` up and running on your local machine: You need to take the following steps to get `al-folio` up and running on your local machine:
@ -237,7 +242,7 @@ $ docker compose pull
$ docker compose up $ docker compose up
``` ```
Note that when you run it for the first time, it will download a docker image of size 400MB or so. Note that when you run it for the first time, it will download a docker image of size 400MB or so. To see the template running, open your browser and go to `http://localhost:8888`. You should see a copy of the theme's demo website.
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. 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.
@ -266,6 +271,8 @@ You can also change the docker image tag to slim! It is a slimmed docker image w
#### Local Setup (Legacy) #### Local Setup (Legacy)
For a hands-on walkthrough of running al-folio locally without using Docker, check out [this cool blog post](https://george-gca.github.io/blog/2022/running-local-al-folio/) by one of the community members!
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)*), and also [Python](https://www.python.org/) and [pip](https://pypi.org/project/pip/) (*hint: for ease of managing python packages, consider using a virtual environment, like [venv](https://docs.python.org/pt-br/3/library/venv.html) or [conda](https://docs.conda.io/en/latest/). If you will use only `jupyter`, you can use [pipx](https://pypa.github.io/pipx/)*). 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)*), and also [Python](https://www.python.org/) and [pip](https://pypi.org/project/pip/) (*hint: for ease of managing python packages, consider using a virtual environment, like [venv](https://docs.python.org/pt-br/3/library/venv.html) or [conda](https://docs.conda.io/en/latest/). If you will use only `jupyter`, you can use [pipx](https://pypa.github.io/pipx/)*).
```bash ```bash
@ -275,8 +282,7 @@ $ pip install jupyter
$ bundle exec jekyll serve --lsi $ bundle exec jekyll serve --lsi
``` ```
Now, feel free to customize the theme however you like (don't forget to change the name!). To see the template running, open your browser and go to `http://localhost:4000`. You should see a copy of the theme's demo website. Now, feel free to customize the theme however you like. After you are done, remember to **commit** your final changes.
After you are done, **commit** your final changes.
--- ---
@ -303,7 +309,7 @@ Starting version [v0.3.5](https://github.com/alshedivat/al-folio/releases/tag/v0
**To enable automatic deployment:** **To enable automatic deployment:**
1. Click on **Actions** tab and **Enable GitHub Actions**; do not worry about creating any workflows as everything has already been set for you. 1. Click on **Actions** tab and **Enable GitHub Actions**; do not worry about creating any workflows as everything has already been set for you.
2. Go to Settings -> Actions -> General -> Workflow permissions, and give **Read and write permissions** to GitHub Actions 2. Go to `Settings -> Actions -> General -> Workflow permissions`, and give `Read and write permissions` to GitHub Actions
3. Make any other changes to your webpage, commit, and push. This will automatically trigger the **Deploy** action. 3. Make any other changes to your webpage, commit, and push. This will automatically trigger the **Deploy** action.
4. 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 `master` branch, your repository should now have a newly built `gh-pages` branch. 4. 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 `master` branch, your repository should now have a newly built `gh-pages` branch.
5. Finally, in the **Settings** of your repository, in the Pages section, set the branch to `gh-pages` (**NOT** to `master`). For more details, see [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source). 5. Finally, in the **Settings** of your repository, in the Pages section, set the branch to `gh-pages` (**NOT** to `master`). For more details, see [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source).
@ -480,6 +486,12 @@ If you have a different question, please ask using [Discussions](https://github.
## Features ## Features
### CV
There are currently 2 different ways of generating the CV page content. The first one is by using a json file located in `assets/json/resume.json`. It is a [known standard](https://jsonresume.org/) for creating a CV programmatically. The second one, currently used as a fallback when the json file is not found, is by using a yml file located in `_data/cv.yml`. This was the original way of creating the CV page content and since it is more human readable than a json file we decided to keep it as an option.
What this means is, if there is no resume data defined in `_config.yml` and loaded via a json file, it will load the contents of `_data/cv.yml` as fallback.
### Publications ### Publications
Your publications' page is generated automatically from your BibTex bibliography. Your publications' page is generated automatically from your BibTex bibliography.