Skip to content

Commit 039027e

Browse files
authored
Improved collections section in CUSTOMIZE guide (alshedivat#3431)
Improved section based on comments from alshedivat#2369. Signed-off-by: George Araújo <george.gcac@gmail.com>
1 parent a599310 commit 039027e

File tree

1 file changed

+93
-4
lines changed

1 file changed

+93
-4
lines changed

CUSTOMIZE.md

Lines changed: 93 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ Here we will give you some tips on how to customize the website. One important t
2929
- [Creating new projects](#creating-new-projects)
3030
- [Adding some news](#adding-some-news)
3131
- [Adding Collections](#adding-collections)
32+
- [Creating a new collection](#creating-a-new-collection)
33+
- [Using frontmatter fields in your collection](#using-frontmatter-fields-in-your-collection)
34+
- [Collections with categories and tags](#collections-with-categories-and-tags)
3235
- [Adding a new publication](#adding-a-new-publication)
3336
- [Author annotation](#author-annotation)
3437
- [Buttons (through custom bibtex keywords)](#buttons-through-custom-bibtex-keywords)
@@ -316,13 +319,99 @@ You can add news in the about page by adding new Markdown files in the [\_news](
316319

317320
## Adding Collections
318321

319-
This Jekyll theme implements [collections](https://jekyllrb.com/docs/collections/) to let you break up your work into categories. The theme comes with three default collections: `news`, `projects`, and `books`. Items from the `news` collection are automatically displayed on the home page, while items from the `projects` collection are displayed on a responsive grid on projects page and items from the `books` collection are displayed on its own `bookshelf` page inside `submenus`.
322+
This Jekyll theme implements [collections](https://jekyllrb.com/docs/collections/) to let you break up your work into categories. The theme comes with three default collections: `news`, `projects`, and `books`. Items from the `news` collection are automatically displayed on the home page, while items from the `projects` collection are displayed on a responsive grid on the projects page, and items from the `books` collection are displayed on its own `bookshelf` page inside `submenus`.
320323

321-
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).
324+
You can easily create your own collections for any type of content—teaching materials, courses, apps, short stories, or whatever suits your needs.
322325

323-
If you wish to create a collection with support for categories and tags, like the blog posts, you just need to add this collection to the `jekyll-archives` section of your [\_config.yml](_config.yml) file. You can check how this is done with the `books` collection. For more information about customizing the archives section or creating your own archives page, check the [jekyll-archives-v2 documentation](https://george-gca.github.io/jekyll-archives-v2/).
326+
### Creating a new collection
324327

325-
To access the collections, you can use the `site.COLLECTION_NAME` variable in your templates.
328+
To create a new collection, follow these steps. We will create a `teaching` collection, but you can replace `teaching` with any name you prefer:
329+
330+
1. **Add the collection to `_config.yml`**
331+
332+
Open the `collections` section in [\_config.yml](_config.yml) and add your new collection:
333+
334+
```yaml
335+
collections:
336+
news:
337+
defaults:
338+
layout: post
339+
output: true
340+
projects:
341+
output: true
342+
teaching:
343+
output: true
344+
permalink: /teaching/:path/
345+
```
346+
347+
- `output: true` makes the collection items accessible as separate pages
348+
- `permalink` defines the URL path for each collection item (`:path` is replaced with the filename)
349+
- Note: You can customize the [permalink structure](https://jekyllrb.com/docs/permalinks/#collections) as needed. If not set, it uses `/COLLECTION_NAME/:name/`.
350+
351+
2. **Create a folder for your collection items**
352+
353+
Create a new folder in the root directory with an underscore prefix, matching your collection name. For a `teaching` collection, create `_teaching/`:
354+
355+
```text
356+
_teaching/
357+
├── course_1.md
358+
├── course_2.md
359+
└── course_3.md
360+
```
361+
362+
3. **Create a landing page for your collection**
363+
364+
Add a Markdown file in `_pages/` (e.g., `teaching.md`) that will serve as the main page for your collection. You can use [\_pages/projects.md](_pages/projects.md) or [\_pages/books.md](_pages/books.md) as a template and adapt it for your needs.
365+
366+
In your landing page, access your collection using the `site.COLLECTION_NAME` variable:
367+
368+
```liquid
369+
{% assign teaching_items = site.teaching | sort: 'date' | reverse %}
370+
371+
{% for item in teaching_items %}
372+
<h3>{{ item.title }}</h3>
373+
<p>{{ item.content }}</p>
374+
{% endfor %}
375+
```
376+
377+
Replace `COLLECTION_NAME` with your actual collection name (e.g., `site.teaching`).
378+
379+
4. **Add a link to your collection page**
380+
381+
Update [\_pages/dropdown.md](_pages/dropdown.md) or the navigation configuration in [\_config.yml](_config.yml) to add a menu link to your new page.
382+
383+
5. **Create collection items**
384+
385+
Add Markdown files in your new collection folder (e.g., `_teaching/`) with appropriate frontmatter and content.
386+
387+
For more information regarding collections, check [Jekyll official documentation](https://jekyllrb.com/docs/collections/) and [step-by=step guide](https://jekyllrb.com/docs/step-by-step/09-collections/).
388+
389+
### Using frontmatter fields in your collection
390+
391+
When creating items in your collection, you can define custom frontmatter fields and use them in your landing page. For example:
392+
393+
```markdown
394+
---
395+
layout: page
396+
title: Introduction to Research Methods
397+
importance: 1
398+
category: methods
399+
---
400+
401+
Course description and content here...
402+
```
403+
404+
Then in your landing page template:
405+
406+
```liquid
407+
{% if item.category == 'methods' %}
408+
<span class="badge">{{ item.category }}</span>
409+
{% endif %}
410+
```
411+
412+
### Collections with categories and tags
413+
414+
If you want to add category and tag support (like the blog posts have), you need to configure the `jekyll-archives` section in [\_config.yml](_config.yml). See how this is done with the `books` collection for reference. For more details, check the [jekyll-archives-v2 documentation](https://george-gca.github.io/jekyll-archives-v2/).
326415

327416
## Adding a new publication
328417

0 commit comments

Comments
 (0)