2

I'm new to Jekyll(Indeed I'm not a front-end developer). In many situations, when using Jekyll I should use site.pages or page.title ect.

In official doc, there are meanings about those variables. However, after reading I'm still confused.

Eg:

  • site.pages: A list of all pages;
  • page.title: The title of the Page;

I'm still wondering what's the meaning of "all pages": all pages in root directory of my project? Or all pages in any depth of my project? Besides what's the definition of pages?

I don't think the doc is clear enough for me. Anyone konws more specific details such as the definition position in code for site.pages? Maybe I can get more if I know where the definition is.

And more:

  • site: Site wide information + configuration settings from _config.yml.

So any more information about all the "site wide information", or the definition positions for these "site wide information"?

Any help is grateful.

puppylpg
  • 909
  • 10
  • 23

1 Answers1

5

At the basic level, there are 5 kinds of data types in Jekyll.

  • Pages
  • Static files
  • Documents
  • Collections
  • Data files

The first two in bold can be seen as content-type primitives. Jekyll uses front matter — key-value pairs enclosed by a pair of three consecutive dashes. e.g:

---
foo: bar
---

— to determine whether a given content-file needs to be processed by Jekyll.

If the file doesn't contain front matter at the very beginning, it is simply copied from source to destination as is without any change. Such a file is known as a Static file.

Otherwise, the contents of the file are sent to be processed which ultimately results in a HTML file. Such files are either Pages or Documents. The difference between these two are whether the files are part of a Collection or not.

A Collection is a set of files contained within a special directory. The directory name starts with an underscore and has to be explicitly listed (without the leading underscore) in the config file for it to be seen as a Collection directory. Files (within a collection) that start their content with front matter are seen as Documents. Those that don't have front matter are simply static files.

Simply put, site.pages comprises of all those files that contain front matter at the very beginning but are themselves not part of any collection. Have such an about.md at the root of your project directory? It is a Page.

Documents inside a collection are accessed via the collection. Therefore, if your site has a Collection labelled movies and couple of files within the directory _movies, then they can be accessed via site.movies

posts are a pre-defined collection and handled with a special status. Individual posts need not contain front matter and they're still accessible via site.posts

ashmaroli
  • 5,209
  • 2
  • 14
  • 25
  • Thanks for your detailed explanation, making me knows a lot. Any doc links about your answer's content? – puppylpg Nov 19 '19 at 04:21
  • Do you know why `CHANGELOG.md` in my root directory is compiled into `CHANGELOG.html` thus appearing at the header of the website? And `README.md`, the same plain markdown without front matter as `CHANGELOG.md`, isn't compiled? – puppylpg Nov 23 '19 at 05:37
  • Files **without front matter** are not converted just copied over to destination. To avoid unnecessary copying, you can list those files under the `exclude` key in your config file. For additional help, I'll need to look at your source repository. – ashmaroli Nov 23 '19 at 08:37
  • Yeah, I know there shouldn't be front matter in the files. But both `README.md` and `CHANGELOG.md` don't have front matter, and these's no difference between them. So i'm just curious why `READMD.md` isn't compiled but `CHANGELOG.md` is compiled. Thanks for your `exclude` suggestion. And if you are willing to see the source repo, [here it is](https://github.com/puppylpg/puppylpg.github.io). Thanks again. – puppylpg Nov 23 '19 at 14:31
  • It is because GitHub Pages bundles a plugin that makes front matter optional. If you build locally with the `--verbose` switch, you'll see that `jekyll-optional-front-matter` is loaded as well as `jekyll-readme-index` which prevents converting `README.md` by default. – ashmaroli Nov 23 '19 at 15:15
  • Thank you. That's the underlying implement I wanna know. So nice of you~~~ – puppylpg Nov 23 '19 at 18:00