Please help me out picking a solid simple structure.
Say I have a single item category (premade cover for a book).
And each item has in the front-matter 1 unique identifier (number) and 5 more identifiers (some with a single value like main genre, and some with multiple values like tags).
Do I understand correctly that I can place all items (up to 500) in one folder and then loop over them on different pages? (like all by number or grouped by the other identifiers).
Now all of the items stay on the site - they will just grow in number by adding items and only up to max 500.
Do I even need a _data/yaml.yml file to organize/structure this?
Is there a benefit of using a collection for this setup? Are there Identifiers I should avoid because they are built into the blogpost feature? Can I still have simple end urls without using folders per genre? Thank you for any pointers and insights.
ā¦ almost forgot - how do I implement a search feature so people can list items by identifiers?
and one more thing - can the item files be html or do they have to be markdown? ā¦ and thinking now about naming them - If I name them by number (101.html 102.html ā¦) I donāt really need the unique number identifier in the front matter, do I ? Or is there a better way of naming them for some reason?
There are a lot of questions here, but I think it is more important to understand what you are trying to accomplish. My apologies for not providing a direct answer just yet. Could you explain what it is you are trying to accomplish?
Is it that you have a book and each file is a chapter and you are trying to make it easy to traverse, search, or just outright read the book?
The use case would be super valuable to understand, otherwise I would potentially give you answers that are not correct based on your needs.
Hi Bill,
It is Book Covers I want to put on the jekyll site. I design them and they are āpremadeā so authors can choose one and have the Title and Text put on.
So, I have one folder where all the premade cover files are in - and they have different styles, genres and colors people would want to search them by. So for example I would want to output one page that shows all the āthrillerā covers and so on. I donāt have the programmer mind and I am looking at all these articles and tutorials and they show so many ways one could go about this will all sorts of filtering techniques - its a bit overwhelming. I found an old tutorial by a Paul Bradley and that kind of applies - he puts together a Planets of the Universe site in jekyll and I can kind of transfer that to my needs - Planets - Types of Planet - the planet / Premade Cover - Types of Premade Covers - the cover.
So. I am assuming I will put all the data in the front matter: genre: thriller / tags: minimal, psycho, noir, monotone / stock-images: free, commercial, mixed and then loop through the covers like {% for cover in site.covers genre=thriller %} create the thriller page ā¦
Now the covers have one unique identifier and that is a number - so the customer can choose unambigously the specific cover. I was going to name each cover file by number like: 101.html - so then I donāt need that in the frontmatter? But looking at a directory it might be nicer to have a filename like 101-thriller-silhouette-dark-colors.html ā¦
So - how would you set this up in a solid and as simple as it needs to be way? Each single view page has the cover image (most important) a description, a price, the stock used and a buy button which will be an email me link until I figure out stripe (no rush).
So my thinking was not to write down a collection since I have to create the 200 item.html files anyways but just to loop throught these using the frontmatter and having a search function that would output the relevant covers on the resulting pages.
It would be nice for me to start with a simple core structure and then add complexity and features later when I understand it fully. A lot of tutorials come with very complex things that are not helpful when starting out and they obscure the view of the underlying structure.
It would be great if you could prevent me from making bad decisons that will later come back to bite me much appreciated.
Thank you for the detailed explanation, and I think we are at a place where it is possible to get down to response for you. I suspect this might take a few conversations as you figure it out.
You have three choices to manage your content. The first is with data, which I believe is what you started with. The second is to create Jekyll collections, which will be a unique file for each book cover. Both are solid approaches and will get the job done. However, there are pros and cons of each approach, as I see it. Also, there is a third hybrid option that helps you manage the collection using files and all the āmetadataā for your covers in a data file.
Data
Easy to access. Many people maintain a database or spreadsheet of their work and then export it to a version that Jekyll supports, like JSON or YAML.
I may have already shared this with you, but I did a four-part video series on working with Jekyll data that I think will be useful for you to watch. Start playing the following video and the other three will auto-play.
PROS
Easy to maintain if you are comfortable working with datasets, especially if you are exporting from another database/spreadsheet.
Fairly easy to maintain and debug since it is just one (or a few) data files.
CONS
It is data, so including HTML or markup in the data can cause lots of headaches.
Depending on how many covers you may have, it might make sense to separate them into various categories just for purposes of making it easier for you to maintain.
For me personally, I like working with data when I have a user interface to do so. I would not want to go into Jekyll using, say, VS Code to make updates. It is just too error-prone.
Collections
In this scenario, every book cover is its own file. It will have its own data and content.
You can read more about collections here:
PROS
Since every page is a file, you will use markup (or HTML) to format the details for each book cover. I could imagine there are some book covers where you might want to add more detail than another. For example, you might want to warn the author that the book cover has font limitations, show some cool layout options, or point to other authors that use a similar design. You can type all this up in markdown and know it will look great, and you donāt have to modify your dataset to do this.
Since you are using markup (or HTML), you can use editors that tend to have better spelling and grammar-checking than, say, a database or spreadsheet tool.
If you go this route and change your mind, the good news is you can use Jekyll to loop through all the pages in the collection and generate valid YML or JSON, so at least you wonāt have to start from scratch.
Letās say you want someone to help you manage the website. You will probably want a good content editor that understands markdown or HTML, not how to work with JSON or YAML files.
CONS
If you want to make bulk changes to many files, you will have to do so manually (there may be some ways to automate this, but it would probably be tricky). For example, letās say you want to add a color tag and include blue or red, so the user can filter by those choices, you will have to open each file individually to do so, where a dataset could [potentially] be much faster.
Just like the data, if you have too many files, it could be hard to manage. You may want to create multiple collections.
Hybrid option
In this example, every cover is a file (101.md, 102.md, etc.). That allows you to create whatever unique content you like for a cover, and you have the flexibility of using spelling and grammar checkers. In the YAML front matter of the file, you would have a book identifier number, like number: 101. Then, you could write code that looks at the book number and gets all the rest of the detail from a data file.
Iām not going to add pros and cons here, but it is something for you to consider.
To data to collection?
While I do not manage your business or know how many files you have or how labor-intensive all this will be, my personal opinion is I like the collections option better. That gives me more freedom to edit each file individually, and as I mentioned, if things feel too much, you can switch to data and even output what you have done to a readable data format. If it feels too tedious to manage all the data for each file, go with the data or hybrid option.
At the end of the day, you will need to play with it and see what you like best. From previous questions, I think you are getting how data works, so I will not include an example of that here. Instead, I will include a collection example. If you want a data example, let me know.
Quick collection tutorial
First, I recommend you use markdown, not HTML, for writing your book descriptions. It will be easier for you to read, and many grammar and spelling checkers understand it [better]. For example, I use Grammarly and while it gets occasionally confused, it at least works over when I use pure html.
Here are the steps to set up a collection for your covers. I suggest you play with this a bit and see how it feels.
At the root of your Jekyll site, edit the _config.yml file and add the following lines (the location does not really matter):
# This section is to configure collections
collections:
covers:
Save the config file, and if necessary, exit and re-run Jekyll, or the setting will not take.
Add a folder to your siteās root and call it: _covers (that is your collection name with an underscore prefix).
Create two files. You can name them whatever you want. Do not get caught up in the naming of the file. In my example, I created two files: 101.md 102.md
Edit the 101.md file and add the following content:
---
number: 101
primaryImage: /assets/covers/101.jpg
---
This is a book cover for 101.
Edit the 102.md file and add the following content:
---
number: 102
primaryImage: /assets/covers/102.jpg
---
## Our most popular design!
This is a unique book cover that you can tailor to meet your specific needs.
Many authors have used this for their work. Here are some links to books using a similar design:
[Amazon](http://amazon.com/booklink1)
[Author's page](https://www.authorpage.com/book)
Note: The first and second files have very different content and layouts, but the YAML front-matter (the data) remains consistent.
Create a folder called assets at the root of your Jekyll site. Then, create a sub-folder called covers. You can create whatever folder structure you wantā¦ I happen to use assets/covers.
Upload at least two files to your assets/covers folder, calling them 101.jpg and 102.jpg. Again, you can name them whatever you want; change the primaryImage setting in each file.
At the root of your site, create a file and name it covers.html.
Edit the contents of covers.html and add the following code (you may have to change the layout to something elseā¦ For this example, I am using the default minima theme Jekyll creates):
Whether you want to go the files route, the dataset route, or a hybrid, I suggest watching that video series I shared earlier in this post. It should really help you wrap your head around using Jekyll files and data.
Hopefully, this is helping you. Feel free to follow up with new questions specific to this answer here. If you have another more generic question, please create a new topic so others can benefit.
PS Jekyll supports data files as CSV too, not just YAML or JSON.
I wrote a tutorial on this
And using a CMS like Forestry or Jekyll Admin makes it easy to edit a data file of any of the formats using neat web GUI. Forestry supports things like defining a book must have a title set and of X characters and a list of authors who have names and URLs for example.
Excellent point, @MichaelCurrin. I only mentioned JSON and YAML as those are [in my own opinion] the easiest to manage visually when writing 1-to-many data files. For example, since @roadie was asking for a single cover that has many genres, you could certainly do that with CSV data, but I feel it would be more difficult to read, manage, and parse. That is also why I left out XML, even though that is perfectly acceptable as well.
I completely agree with you that using something like Forestry is perfect for this because you can set up a template with fields that are required/not required and has a nice UI to make sure you follow appropriate standards. As a matter of fact, I use their front matter templates for my podcast posts, just to make sure I donāt forget anything ā which I would totally do otherwise
great input, thank you very much for the detailed answers. So it seems I can just put all the info in the frontmatter and refer to those keys with āpage.keyā when I need to use the value. Itās all a bit overwhelming and complex. With all the planning it is inevitable that I need to adjust the html contents along the way when I learn something but with emacs doing a query replace regex on thousands of files is no issue so I am a bit hopeful. Also it seems I can create an index in json for a search feature. Looking into that next. Very happy to learn so much. I have started to watch the videos from Bill Raymond, very good.
confidence is the feeling I have before I understand the situation
Great mini-tutorial. I just came across this today and gee I wish I had seen this when I was first learning to use Jekyll. You explain it so well and give examples too!
Iāve been looking at your tutorial for collections and wondering if it is really necessary that every folder I setup for each collection always have an index.md or index.html file? Or is that index file only necessary if you want to display a list or the contents of that collection on a specific page?
For instance, if I have a RECIPES collection and a folder named Recipes, and subfolders within that folder for Dinner, Lunch, Breakfast, Snacks. Do I need to also have index.html files within each of those subfolders as well?
The index file is just useful to show the list of items in the collection. Sometimes people will even modify the URL to go to /recipes for example so having something there is just a good practice, not a requirement.
much appreciated.