forked from alshedivat/al-folio
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Upgrading the README file (alshedivat#2034)
I decided to break the README file into different ones to declutter it from the main page. Also adding some more explanation on the structure of the template. Tackling alshedivat#2032 and alshedivat#2033 --------- Signed-off-by: George Araujo <george.gcac@gmail.com>
- Loading branch information
1 parent
3f9a2bc
commit a67fe1f
Showing
25 changed files
with
480 additions
and
409 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| # Customize | ||
|
|
||
| Here we will give you some tips on how to customize the website. | ||
|
|
||
| ## Project structure | ||
|
|
||
| The project is structured as follows, focusing on the main components that you will need to modify: | ||
|
|
||
| ```txt | ||
| . | ||
| ├── 📄 404.html: 404 page (page not found) | ||
| ├── 📂 assets/: contains the assets that are displayed in the website | ||
| │ └── 📂 json/ | ||
| │ └── 📄 resume.json: CV in JSON format (https://jsonresume.org/) | ||
| ├── 📂 _bibliography/ | ||
| │ └── 📄 papers.bib: bibliography in BibTeX format | ||
| ├── 📄 _config.yml: the configuration file of the template | ||
| ├── 📂 _data/: contains some of the data used in the template | ||
| │ ├── 📄 cv.yml: CV in YAML format, used when assets/json/resume.json is not found | ||
| │ └── 📄 repositories.yml: users and repositories info in YAML format | ||
| ├── 📂 _includes/: contains code parts that are included in the main HTML file | ||
| ├── 📂 _layouts/: contains the layouts to choose from in the frontmatter of the Markdown files | ||
| ├── 📂 _news/: the news that will appear in the news section in the about page | ||
| ├── 📄 news.html: defines the news section layout in the about page | ||
| ├── 📂 _pages/: contains the pages of the website that are shown in the header | ||
| ├── 📂 _posts/: contains the blog posts | ||
| ├── 📂 _projects/: contains the projects | ||
| └── 📂 _sass/: contains the SASS files that define the style of the website | ||
| ├── 📄 _base.scss: base style of the website | ||
| ├── 📄 _cv.scss: style of the CV page | ||
| ├── 📄 _distill.scss: style of the Distill articles | ||
| ├── 📄 _layout.scss: style of the overall layout | ||
| ├── 📄 _themes.scss: themes colors and a few icons | ||
| └── 📄 _variables.scss: variables used in the SASS files | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| The configuration file [_config.yml](_config.yml) contains the main configuration of the website. Most of the settings is self-explanatory and we also tried to add as much comments as possible. If you have any questions, please check if it was not already answered in the [FAQ](FAQ.md). | ||
|
|
||
| > Note that the `url` and `baseurl` settings are used to generate the links of the website, as explained in the [install instructions](INSTALL.md). | ||
| All changes made to this file are only visible after you rebuild the website. That means that you need to run `bundle exec jekyll serve --lsi` again if you are running the website locally or push your changes to GitHub if you are using GitHub Pages. All other changes are visible immediately, you only need to refresh the page. | ||
|
|
||
| ## Modifying the CV information | ||
|
|
||
| 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](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](_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](_config.yml) and loaded via a json file, it will load the contents of [_data/cv.yml](_data/cv.yml). If you want to use the [_data/cv.yml](_data/cv.yml) file as the source of your CV, you must delete the [assets/json/resume.json](assets/json/resume.json) file. | ||
|
|
||
| ## Modifying the user and repository information | ||
|
|
||
| The user and repository information is defined in [_data/repositories.yml](_data/repositories.yml). You can add as many users and repositories as you want. Both informations are used in the `repositories` section. | ||
|
|
||
| ## Creating new pages | ||
|
|
||
| You can create new pages by adding new Markdown files in the [_pages](_pages/) directory. The easiest way to do this is to copy an existing page and modify it. You can choose the layout of the page in the [frontmatter](https://jekyllrb.com/docs/front-matter/) of the Markdown file. You can also add new layouts in the [_layouts](_layouts/) directory if you feel the need for it. | ||
|
|
||
| ## Creating new blog posts | ||
|
|
||
| To create a new blog post, you can add a new Markdown file in the [_posts](_posts/) directory. The name of the file must follow the format `YYYY-MM-DD-title.md`. The easiest way to do this is to copy an existing blog post and modify it. Note that some blog posts have optional fields in the [frontmatter](https://jekyllrb.com/docs/front-matter/) that are used to enable specific behaviors or functions. | ||
|
|
||
| If you want to create blog posts that are not ready to be published, but you want to track it with git, you can create a [_drafts](https://jekyllrb.com/docs/posts/#drafts) directory and store them there. | ||
|
|
||
| ## Creating new projects | ||
|
|
||
| You can create new projects by adding new Markdown files in the [_projects](_projects/) directory. The easiest way to do this is to copy an existing project and modify it. | ||
|
|
||
| ## Adding some news | ||
|
|
||
| You can add news in the about page by adding new Markdown files in the [_news](_news/) directory. There are currently two types of news: inline news and news with a link. News with a link take you to a new page while inline news are displayed directly in the about page. The easiest way to create yours is to copy an existing news and modify it. | ||
|
|
||
| ## Adding Collections | ||
|
|
||
| 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. | ||
|
|
||
| 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](_config.yml) file, create a corresponding folder, and create a landing page for your collection, similar to [_pages/projects.md](_pages/projects.md). | ||
|
|
||
| ## Adding a new publication | ||
|
|
||
| To add publications create a new entry in the [_bibliography/papers.bib](_bibliography/papers.bib) file. You can find the BibTeX entry of a publication in Google Scholar by clicking on the quotation marks below the publication title, then clicking on "BibTeX", or also in the conference page itself. By default, the publications will be sorted by year and the most recent will be displayed first. You can change this behavior and more in the `Jekyll Scholar` section in [_config.yml](_config.yml) file. | ||
|
|
||
| You can add extra information to a publication, like a PDF file in the `assets/pdfs/` directory and add the path to the PDF file in the BibTeX entry with the `pdf` field. Some of the supported fields are: `abstract`, `altmetric`, `arxiv`, `bibtex_show`, `blog`, `code`, `dimensions`, `doi`, `eprint`, `html`, `isbn`, `pdf`, `pmid`, `poster`, `slides`, `supp`, `video`, and `website`. | ||
|
|
||
| ### Author annotation | ||
|
|
||
| In publications, the author entry for yourself is identified by string array `scholar:last_name` and string array `scholar:first_name` in [_config.yml](_config.yml). For example, if you have the following entry in your [_config.yml](_config.yml): | ||
|
|
||
| ```yaml | ||
| scholar: | ||
| last_name: [Einstein] | ||
| first_name: [Albert, A.] | ||
| ``` | ||
| If the entry matches one form of the last names and the first names, it will be underlined. Keep meta-information about your co-authors in [_data/coauthors.yml](_data/coauthors.yml) and Jekyll will insert links to their webpages automatically. The co-author data format is as follows, | ||
| ```yaml | ||
| "Adams": | ||
| - firstname: ["Edwin", "E.", "E. P.", "Edwin Plimpton"] | ||
| url: https://en.wikipedia.org/wiki/Edwin_Plimpton_Adams | ||
|
|
||
| "Podolsky": | ||
| - firstname: ["Boris", "B.", "B. Y.", "Boris Yakovlevich"] | ||
| url: https://en.wikipedia.org/wiki/Boris_Podolsky | ||
|
|
||
| "Rosen": | ||
| - firstname: ["Nathan", "N."] | ||
| url: https://en.wikipedia.org/wiki/Nathan_Rosen | ||
|
|
||
| "Bach": | ||
| - firstname: ["Johann Sebastian", "J. S."] | ||
| url: https://en.wikipedia.org/wiki/Johann_Sebastian_Bach | ||
|
|
||
| - firstname: ["Carl Philipp Emanuel", "C. P. E."] | ||
| url: https://en.wikipedia.org/wiki/Carl_Philipp_Emanuel_Bach | ||
| ``` | ||
| If the entry matches one of the combinations of the last names and the first names, it will be highlighted and linked to the url provided. | ||
| ### Buttons (through custom bibtex keywords) | ||
| There are several custom bibtex keywords that you can use to affect how the entries are displayed on the webpage: | ||
| - `abbr`: Adds an abbreviation to the left of the entry. You can add links to these by creating a venue.yaml-file in the _data folder and adding entries that match. | ||
| - `abstract`: Adds an "Abs" button that expands a hidden text field when clicked to show the abstract text | ||
| - `altmetric`: Adds an [Altmetric](https://www.altmetric.com/) badge (Note: if DOI is provided just use `true`, otherwise only add the altmetric identifier here - the link is generated automatically) | ||
| - `arxiv`: Adds a link to the Arxiv website (Note: only add the arxiv identifier here - the link is generated automatically) | ||
| - `bibtex_show`: Adds a "Bib" button that expands a hidden text field with the full bibliography entry | ||
| - `blog`: Adds a "Blog" button redirecting to the specified link | ||
| - `code`: Adds a "Code" button redirecting to the specified link | ||
| - `dimensions`: Adds a [Dimensions](https://www.dimensions.ai/) badge (Note: if DOI or PMID is provided just use `true`, otherwise only add the Dimensions' identifier here - the link is generated automatically) | ||
| - `html`: Inserts an "HTML" button redirecting to the user-specified link | ||
| - `pdf`: Adds a "PDF" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory) | ||
| - `poster`: Adds a "Poster" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory) | ||
| - `slides`: Adds a "Slides" button redirecting to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory) | ||
| - `supp`: Adds a "Supp" button to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory) | ||
| - `website`: Adds a "Website" button redirecting to the specified link | ||
|
|
||
| You can implement your own buttons by editing the [_layouts/bib.html](_layouts/bib.html) file. | ||
|
|
||
| ## Changing theme color | ||
|
|
||
| A variety of beautiful theme colors have been selected for you to choose from. The default is purple, but you can quickly change it by editing the `--global-theme-color` variable in the [_sass/_themes.scss](_sass/_themes.scss) file. Other color variables are listed there as well. The stock theme color options available can be found at [_sass/_variables.scss](_sass/_variables.scss). You can also add your own colors to this file assigning each a name for ease of use across the template. | ||
|
|
||
| ## Adding social media information | ||
|
|
||
| You can add your social media links by adding the specified information at the `Social integration` section in the [_config.yml](_config.yml) file. This information will appear at the bottom of the `About` page. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| # Frequently Asked Questions | ||
|
|
||
| Here are some frequently asked questions. If you have a different question, please check if it was not already answered in the Q&A section of the [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions/categories/q-a). If not, feel free to ask a new question there. | ||
|
|
||
| - [After I create a new repository from this template and setup the repo, I get a deployment error. Isn't the website supposed to correctly deploy automatically?](#after-i-create-a-new-repository-from-this-template-and-setup-the-repo-i-get-a-deployment-error-isnt-the-website-supposed-to-correctly-deploy-automatically) | ||
| - [I am using a custom domain (e.g., `foo.com`). My custom domain becomes blank in the repository settings after each deployment. How do I fix that?](#i-am-using-a-custom-domain-eg-foocom-my-custom-domain-becomes-blank-in-the-repository-settings-after-each-deployment-how-do-i-fix-that) | ||
| - [My webpage works locally. But after deploying, it fails to build and throws `Unknown tag 'toc'`. How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-fails-to-build-and-throws-unknown-tag-toc-how-do-i-fix-that) | ||
| - [My webpage works locally. But after deploying, it is not displayed correctly (CSS and JS is not loaded properly). How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-is-not-displayed-correctly-css-and-js-is-not-loaded-properly-how-do-i-fix-that) | ||
| - [Atom feed doesn't work. Why?](#atom-feed-doesnt-work-why) | ||
| - [My site doesn't work when I enable `related_blog_posts`. Why?](#my-site-doesnt-work-when-i-enable-related_blog_posts-why) | ||
| - [When trying to deploy, it's asking for github login credentials, which github disabled password authentication and it exits with an error. How to fix?](#when-trying-to-deploy-its-asking-for-github-login-credentials-which-github-disabled-password-authentication-and-it-exits-with-an-error-how-to-fix) | ||
|
|
||
| --- | ||
|
|
||
| #### After I create a new repository from this template and setup the repo, I get a deployment error. Isn't the website supposed to correctly deploy automatically? | ||
|
|
||
| Yes, if you are using release `v0.3.5` or later, the website will automatically and correctly re-deploy right after your first commit. Please make some changes (e.g., change your website info in `_config.yml`), commit, and push. Make sure to follow [deployment instructions](https://github.com/alshedivat/al-folio#deployment). (Relevant issue: [209](https://github.com/alshedivat/al-folio/issues/209#issuecomment-798849211).) | ||
|
|
||
| #### I am using a custom domain (e.g., `foo.com`). My custom domain becomes blank in the repository settings after each deployment. How do I fix that? | ||
|
|
||
| You need to add `CNAME` file to the `master` or `source` branch of your repository. The file should contain your custom domain name. (Relevant issue: [130](https://github.com/alshedivat/al-folio/issues/130).) | ||
|
|
||
| #### My webpage works locally. But after deploying, it fails to build and throws `Unknown tag 'toc'`. How do I fix that? | ||
|
|
||
| Make sure you followed through the [deployment instructions](#deployment) in the previous section. You should have set the deployment branch to `gh-pages`. (Related issue: [1438](https://github.com/alshedivat/al-folio/issues/1438).) | ||
|
|
||
| #### My webpage works locally. But after deploying, it is not displayed correctly (CSS and JS is not loaded properly). How do I fix that? | ||
|
|
||
| Make sure to correctly specify the `url` and `baseurl` paths in `_config.yml`. Set `url` to `https://<your-github-username>.github.io` or to `https://<your.custom.domain>` if you are using a custom domain. If you are deploying a personal or organization website, leave `baseurl` blank. If you are deploying a project page, set `baseurl: /<your-project-name>/`. If all previous steps were done correctly, all is missing is [for your browser to fetch again the site stylesheet](https://github.com/alshedivat/al-folio/issues/1398#issuecomment-1609518404). | ||
|
|
||
| #### Atom feed doesn't work. Why? | ||
|
|
||
| Make sure to correctly specify the `url` and `baseurl` paths in `_config.yml`. RSS Feed plugin works with these correctly set up fields: `title`, `url`, `description` and `author`. Make sure to fill them in an appropriate way and try again. | ||
|
|
||
| #### My site doesn't work when I enable `related_blog_posts`. Why? | ||
|
|
||
| This is probably due to the [classifier reborn](https://github.com/jekyll/classifier-reborn) plugin, which is used to calculate related posts. If the error states `Liquid Exception: Zero vectors can not be normalized...`, it means that it could not calculate related posts for a specific post. This is usually caused by [empty or minimal blog posts](https://github.com/jekyll/classifier-reborn/issues/64) without meaningful words (i.e. only [stop words](https://en.wikipedia.org/wiki/Stop_words)) or even [specific characters](https://github.com/jekyll/classifier-reborn/issues/194) you used in your posts. Also, the calculus for similar posts are made for every `post`, which means every page that uses `layout: post`, including the announcements. To change this behavior, simply add `related_posts: false` to the front matter of the page you don't want to display related posts on. | ||
|
|
||
| #### When trying to deploy, it's asking for github login credentials, which github disabled password authentication and it exits with an error. How to fix? | ||
|
|
||
| Open .git/config file using your preferred editor. Change the `https` portion of the `url` variable to `ssh`. Try deploying again. |
Oops, something went wrong.